HCL Lotus Expeditor wiki: Lotus Expeditor 6.2.3 Integrator Documentation: Configuration of the Expeditor integrator

Configuration of the Expeditor integrator

Added by ~Emile Asatoolitader | Edited by ~Maria Asaresterynds on April 4, 2017 | Version 10

Actions ▼

Abstract

Abstract

No abstract provided.

Tags: Integrator

Return to Main Contents

ShowTable of Contents

HideTable of Contents

1 Configuration Overview
2 Common Configuration Settings
3 Local Lotus Expeditor micro broker and micro broker bridge Configuration
4 Resource Monitor (Section 5) and Resource Adapter Configuration (Section 6)
5 Other Adapters and Platform Access Options
- 5.1 REST Adapter (Section_7)
  - 5.1.1 Overview
  - 5.1.2 REST Adapter Configuration
- 5.2 Graphical User Interface Access Configuration (Section_17)
6 Expeditor integrator Resource Mapper Configuration (Section_8)
7 Application Control Service Configuration (Section_9)
8 Custom Log Service configuration (Section_11)
9 Custom Event Service configuration (Section_12)
10 Expeditor integrator Tivoli Monitoring Service Configuration - TECLCF utility
- 10.1 iTMS Configuration Options (Section_13)
- 10.2 Using Tivoli Endpoints on the Store Server for forwarding TEC Events
11 Further Services
12 Password encryption utility

This section explains how the Expeditor integrator can be configured so that it works with file servers (e.g. the FTP server on a 4690 PoS Controller), databases and the back-end messaging system (e.g. with IBM Message Broker and the Tivoli Enterprise Console, TEC).

(Note: APPENDIX A – Custom Set-up contains a suggestion for a configuration sheet which can be used to provide to save the required configuration values.)

Configuration Overview

The Expeditor integrator can be configured using different methods:

The IBM Lotus Expeditor integrator is delivered as self-contained installation package. Within the installation package, all Expeditor integrator functions are provided as Eclipse RCP features in an Eclipse Update Site. Standard Eclipse RCP management tools can be used to deploy Expeditor integrator to existing IBM Lotus Expeditor client installations. IBM offers the IBM Lotus Expeditor Server for this installation and management option (see ‎Ref_10 and ‎Ref_11).
Since the Expeditor integrator and its bundles are loosely coupled components (OSGi Bundles) that consequently use the standard OSGi Configuration Admin Service, all configuration values are stored in the bundles configuration store. Based on the OMA/DM standard, these configuration values are remotely accessible and changeable.

This standard access to configuration parameters provides IBM through its IBM WebSphere Premises Server. Configuration jobs can remotely access the Expeditor integrator and change configuration parameters. In environments where IBM RFID solutions are also deployed in the remote locations, this is the preferred method with the smallest operational effort in the back-end (see ‎Ref_16 and ‎Ref_17).
Expeditor integrator can be directly configured through its configuration file which is located in <XPDINTEG_HOME>/config/XPDinteg.xml. This file is an XML structured file which holds all configurable properties of the Expeditor integrator. The XML structure allows for validation, human-readability and enables graphical UI support for configuration purposes (see chapter ‎7.5 Configuration Tool page).

The configuration in the XPDinteg.xml is adjusted by changing configuration properties manually, through specific Expeditor integrator configuration messages or by including a complete new configuration file XPDinteg.xml in a ConfigurationUpdate message and deploying it to its directory in the Expeditor integrator.

These methods require their own flow in the Expeditor integrator Application Control Service (ACS). A new configuration file is deployed to the config/new directory by:
1. transmitting it from the back-end using the Default_ConfigUpdate.flow (see ‎Ref_2.). This is based on the File Transfer use case which allows for detaching the configuration file in the message (XPDinteg.xml) to the config directory and kicks off the update flow.
2. manually copying it into the config/new directory. This is based on a File Resource Monitor Adapter use case (This use case monitors the config/new directory and fires an event when a new file appears in the config/new directory to start the Default_ConfigUpdateManual.flow, see ‎Ref_2. This flow initiates the re-reading of the configuration file.).
  
  A final CreateEventAdminEventActivity will then inform the Custom Config Service (refer to chapter ‎5.2 Remote Platform Restart). The latter adds the changes to each Expeditor integrator Bundle configuration store.
  
  There is also the possibility to send only one or a list of configuration parameters in specific ChangeProperties control messages rather then transmitting a complete configuration file.
  
  This approach is on a fire and forget basis. Although, the configuration update flows run as local transactions, applying a wrong configuration may cause the Expeditor integrator being unable to work. In this case Expeditor integrator might not be accessible from the back-end services anymore.
Selected configuration settings for message payloads can be provided in the message header. This allows for flexible message handling for each message. Since not all configuration parameters can be set with this method, it will always need parts of methods 1 or 2.

Note: If parameter values are provided in the JMS message header, these parameters are preferred over the locally stored settings (JMS message parameter overrules local settings in flow definitions and in the XPDinteg.xml).
Also, some configuration parameters can be provided in ACS flows. Selected Activities allow for being configured in the flow definition file (e.g. DestinationPath and DestinationName). Please, refer to the Activity description in ‎Ref_2 for more details.

Note: If parameter values are provided in the ACS flows, these parameters are preferred over the locally stored settings in XPDinteg.xml, but they are overwritten with custom settings in JMS headers.

Figure 6 shows which sections in the XPDinteg.xml configuration file are required for adjusting Expeditor integrator to customer environments. The following chapters also refer to these configuration sections.

Important sections in XPDinteg.xml configuration file

Figure 6: Important sections in XPDinteg.xml configuration file

he provided config/XPDinteg.xml contains a minimal start-up configuration. It allows for transferring files to and from the local file system. Default LocalFileSystem_Adapters are included for the <XPDINTEG_HOME>/datatrans/inbound and outbound directories. Please, also refer to the files in these directories.

The config/system/XPDintegDefaultRoles.xml file is also shipped with default users and roles for accessing the Expeditor integrator instance, for example when using the REST Adapter or the Expeditor integrator GUI (see section ‎7). Please, refer to section ‎8 for applying changes to these default User Admin Service settings.

The following chapters of this section describe the possible configuration settings of Expeditor integrator. Different configuration domains are explained in detail (configuration sections). These sections are referenced in the XPDinteg.xml configuration file. The XPDinteg.xml file can be edited directly using a text editor or by using the Expeditor integrator Configuration Tool (see chapter ‎7.5 Configuration Tool page).

If a messaging back-end is used, the Expeditor integrator must be configured to be able to access the AI MQ Back-end Server (see chapter Resource Monitor and Resource Adapter Configuration).

For example, a typical retail environment would also require access to attached resources, such as the FTP Server of the 4690 PoS controller. The Resource Adapter configuration is described in chapter Resource Monitor and Resource Adapter Configuration and ‎Other Adapters and Platform Access Option).

Chapter Application Control Service Configuration explains how the use case execution, e.g. for the Local File Transfer or for the retail environment example, can be configured.

Addtional configuration options are listed in the section Further services ( HouseKeeping, Transaction Service and Persistence Service).

Password credentials (e.g. for FTP server access) can be encrypted by using the delivered PasswordUtil tool (see chapter Password encryption utility).

The XPDinteg.xml file contains all configuration settings of the Expeditor integrator. A default file and a sample file for a typical retail environment (Sample_XPDinteg.xml) are included in the samples folder.

Common Configuration Settings

This chapter contains the COMMON configuration parameters for all components of Expeditor integrator (in <common></common> section of SECTION_1 in the XPDinteg.xml file). For example, the LocationId (previous StoreId) must be provided here.

Location Id

The Location ID is the unique identification of the Expeditor integrator runtime in the customer’s environment. The Location ID is used to address messages to the correct Expeditor integrator. If this value is not set or not unique, messages will not be received nor processed properly.

Therefore, it is recommended to use a unique business identification of the remote location for the Location ID (for example, the Store ID for retail stores or the Station ID for petrol stations).

General format:

<id>location_id</id>

(An example is included in Listing 4 in chapter ‎4.2.3 Expeditor integrator JMS header Mapping / Mixed version support).

Configuration Management Option

Lotus Expeditor integrator configuration allows for being managed manually by changing the XPDinteg.xml file, but can also be remotely managed by either the Expeditor Client Manager of the Lotus Expeditor Server or by the IBM WebSphere Premises Server (Pleaser, refer to chapter Configuration Overview for more details).

General format:

<server-managed>NONE</server-managed>

Possible values:

NONE - Expeditor integrator runtime is manually configured by editing the XPDinteg.xml file and copying it into the config/new folder.
ECM - Expeditor Client Manager of the IBM Lotus Expeditor Server is remotely managing this runtime. Note: Manual changes to the XPDinteg.xml will bring this configuration out of sync with the ECM Server configuration!
PREMISES - Expeditor integrator runtime configuration is remotely managed by the IBM WebSphere Premises Server.

Note: Manual changes to the XPDinteg.xml will bring this configuration out of sync with the Premises configuration!

Expeditor integrator JMS Header Mapping and Mixed version support

The current release v2 of Expeditor integrator introduces improvements and extensions to the features of v1. This required adjustments in the JMS Custom Header properties of the messages through which the back-end system and other JMS clients can interact with Expeditor integrator. Since changes like this might be required for future versions as well, a new JMS Custom Header property HeaderVersion is included and the new header mapping function is provided. This allows for operation of Expeditor integrator runtimes in environments with mixed release versions.

The Header Version Mapper analyzes the HeaderVersion property and can then map the configured JMS Custom Header parameters of the received version to the internally used header format (inbound mapping). The internally used HeaderVersion is always compliant to the runtime release version (so, in Expeditor integrator v2.0, messages are internally handled as messages with HeaderVersion=2.0).

It is also possible to map the internal JMS Header format to another HeaderVersion for all messages that are sent from the Expeditor integrator to the back-end (outbound mapping).

NOTE: If the mandatory HeaderVersion parameter is not present, it is assumed that the message is of Expeditor integrator v1.0 message format.

General format:

<inbound_versionmappings>

     <version number="received_header_version">

          <headermapping name="header_property_name_A_in_received_header" currentname=" header_property_name_A_in_this_platforms_header "/>

     </version>

</inbound_versionmappings>

<outbound_versionmappings>

     <version number="send_header_version">

          <headermapping name="header_property_name_B_in_send_header“ currentname=" header_property_name_B_in_this_platforms_header "/>

     </version>

</outbound_versionmappings>

Listing 4 shows the example configuration which is used to connect Expeditor integrator v2.0 runtime to MessageBroker flows developed for Expeditor integrator v1.0. The Expeditor integrator runtime receives v1.0 messages and replaces the JMS Custom Header property “StoreId” with “LocationId” in incoming messages and also sends messages in v1.0 format back by replacing the property “LocationId” with “StoreId”.

Listing 4: JMS Header property mapping for the future.

<common>

     <id>location_id</id>

     <server-managed>NONE</server-managed>

     <inbound_versionmappings>

          <version number="1.0">

               <headermapping name="StoreId" currentname="LocationId"/>

          </version>

     </inbound_versionmappings>

     <outbound_versionmappings>

          <version number="1.0">

               <headermapping name="StoreId" currentname="LocationId"/>

          </version>

     </outbound_versionmappings>

...

CBE Event Structure Configuration

IBM Lotus Expeditor integrator is an event-driven application. The Custom Log Service and the Custom Event Service create log and business events conform to the standardized Common Base Event (CBE) structure (see Ref_20).

The CBE standard structure can be further extended with custom attributes and custom data elements. The <cbe> section within the <common> part of the XPDinteg.xml allows for adding such custom properties.

General format:

<namespaceVerification>true</namespaceVerification>

     <attribute-mappings>

          <attribute-mapping>

               <attribute name="extensionName" type="string" value="&lt;jms_custom_header_property&gt;" mandatory="true"/>

          </attribute-mapping>

...

     </attribute-mappings>

     <extended-data-element-mappings>

          <element-mapping name=“element1" type="noValue" mandatory="true">

               <value>value1</value>

               <value>&lt;DestinationPath&gt;</value>

          </element-mapping>

     <element-mapping name="element2" type="noValue" mandatory="true">

...

     </extended-data-element-mappings>

Note: JMS Custom Header properties and other well-known Expeditor integrator variable values can also be included in the CBE event. These properties are indicated as placeholders in the following format:

<jms_custom_header_property> what is represented as &lt;jms_custom_header_property&gt;

in XML.

Table 8: CBE Custom structure configuration options

Property	Explanation
<cbe> <dump>	Tag which declares the <dump> element. The <dump> element includes a list of all currently in the ACS flow context available property-value pairs (e.g. if the ACS flow was triggered by a JMS message, all JMS Custom Header properties will be included).
<value>	Tag which defines when the <dump> element should be included in the CBE. Possible values are: <value>TRANSACTION_STARTED</value> <value>TRANSACTION_COMPLETED</value> <value>TRANSACTION_PROCESSING</value> <value>TRANSACTION_FAILED</value> This means that the CBE event with TRANSACTION_STARTED will include the <dump> element.
<namespaceVerification>	Optional parameter: Boolean “true \| false” Tag definjes whether the CBE XML name space tag (xmlns) is included as property in the CBE event header. Applications processing the Expeditor integrator log and/or event CBEs may or may not required the CBE name space definition (e.g. WebSphere Transformation Extender or WebSphere Business Monitor). default = true (also set to true when parameter not present)
<attribute-mappings> <attribute-mapping>	Tag which indicators for the CBE attribute mappings
<attribute name="	"my_extension_name“ String: name of the additional attribute in the CBE header
type="	"string" type of the extension attribute
value="	“my_value” value of the extension attribute. Place holders for Expeditor integrator context variable values are indicated by <jms_custom_header_property> what is represented in XML like this: value=“*jms_custom_header_property*”
mandatory="	"true" OR "false“ defines whether attribute must always be included or not
<extended-data-element-mappings>	Defines the CBE Extended Data Elements
<element-mapping name=	“*element1*" String: name of the additional extended data element in the CBE
type=	"noValue" type of the extended data element
mandatory=	"true" OR “false” defines whether attribute must always be included or not
<value>	“*my_value” value of the extended data element. Place holders for Expeditor integrator context variable values are indicated by <jms_custom_header_property> what is represented in XML like this: <value><DestinationPath>*</value>

Listing 5: CBE Custom structure definition example

<common>

     <cbe>

     <namespaceVerification>true</namespaceVerification>

     <!-- CBE event structure configuration -->

          <dump>

               <value>TRANSACTION_STARTED</value>

               <value>TRANSACTION_FAILED</value>

          </dump>

          <attribute-mappings>

               <attribute-mapping>

                    <attribute name="extensionName" type="string" value="&lt;ExtensionName&gt;" mandatory="true"/>

               </attribute-mapping>

          </attribute-mappings>

          <extended-data-element-mappings>

               <element-mapping name="DestinationPath" type="string" mandatory="true">

                    <value>&lt;DestinationPath&gt;</value>

               </element-mapping>

               <element-mapping name="DestinationName" type="string" mandatory="true">

                    <value>&lt;DestinationName&gt;</value>

               </element-mapping>

          </extended-data-element-mappings>

...

Expeditor integrator User Access Control

The IBM Expeditor integrator uses the Lotus Expeditor Web Container for the REST Adapter (see chapter ‎4.5.1 REST Adapter) and for the Expeditor integrator GUI (see section ‎7). This access can be secured based on user names, passwords and roles (see Expeditor integrator User Access Control).

Per default, Expeditor integrator uses the Expeditor User Admin Service. The Expeditor User Admin Service keeps its configuration in the User Admin (configuration) store. Like other Eclipse platform configuration data, this store is wiped out when the platform is reset (the workspace folder is deleted). It is also empty after the first installation of Expeditor integrator. Therefore, an initial default configuration is loaded from the XPDintegDefaultRoles.xml file.

Currently, the Expeditor integrator can only configure the User Admin store through its own configuration file based methods. An option for future integration of directory service support is also provided (for LDAP, for example).

The name and the location of the two user admin configuration files is configurable in the <common> section of the Expeditor integrator configuration.

General format:

<user-registry type="USERADMIN">

     <params>

          <param name="DefaultsFileLocation" value="config/system/XPDintegDefaultRoles.xml"</param>

          <param name="UpdatesType" value="FILE"</param>

          <param name="UpdatesFileLocation" value="config/XPDintegRoles.xml"</param>

          <param name="UpdatesFileAction" value="DELETE"/>

     </params>

</user-registry>

The properties in Table 9 are used for defining the way of how Expeditor integrator uses and configures the User Admin Service as well as for setting the configuration location information.

Table 9: Configuration of User Admin service access in XPDinteg.xml

Property	Description and Values
<user-registry>	Indicates the user admin configuration section
type	Specifies the type of user-registry. Currently only “USERADMIN”. Possible extensions for future.
DefaultsFileLocation	Location of the configuration file that contains all required Expeditor integrator default users, roles and passwords so that a new or reset platform can re-start and operate. Per default, this file is located in the config/system folder: <XPDINTEG_HOME>/config/*system/XPDintegDefault*Roles.xml>
UpdatesType	Defines the way how the configuration parameters are updated. Currently, only local Expeditor integrator configuration files and Expeditor Client Manager (ECM) Server are supported. value: FILE \| ECM (in the future, values: FILE \| ECM \| LDAP \| …)
UpdatesFileLocation	Location of the file that contains the current users, roles and passwords specific to a single Expeditor integrator instance. This file is updated with the values received during a ConfigUpdate process. Per default, this file is located in the config/ folder: <XPDINTEG_HOME>/*config/*XPDintegRoles.xml>
UpdatesFileAction	Defines how the received update file (for updatesType=FILE) is handled after the User Admin configuration update was applied. Possible values: DELETE - no XPDintegRoles.xml type file is locally stored apart from the config/system/XPDintegDefaultRoles.xml file (e.g. due to security constraints) NONE - received updates file is stored in under the default location <XPDINTEG_HOME>/config>. Important: The name of the transferred file is maintained! WriteOther - received update file is stored under the name and location specified under updatesFileLocation

Listing 6 presents an example configuration for using Expeditor integrator configuration files to populate the User Admin Service configuration store.

Listing 6: Definition of configuration location for users and roles in XPDinteg.xml (default roles are defined in file XPDintegDefaultRoles.xml, updates to User Admin service are provided in file XPDintegRoles.xml)

<common>

     <id>Store100</id>

     <server-managed>NONE</server-managed>

     <user-registry type="USERADMIN">

          <params>

               <param name="DefaultsFileLocation " value="config/system/XPDintegDefaultRoles.xml"</param>

               <param name="UpdatesType " value="FILE"</param>

               <param name="UpdatesFileLocation " value="config/XPDintegRoles.xml"</param>

               <param name="UpdatesFileAction" value="DELETE"</param>

     ></params>

     </user-registry>

...

</common>

...

Listing 7 gives an example configuration for using the Expeditor Client Manager (Expeditor Server) for managing the User Admin service configuration. In this example, the initial configuration after platform reset is retrieved from the XPDintegDefaultRoles.xml file. Then, the ECM agent is triggered (only once). The ECM agent contacts the ECM server, looks for update jobs and applies them if some exist.

Listing 7: Definition of configuration location for users and roles in XPDinteg.xml (default roles are retrieved from XPDintegDefaultRoles.xml and updates are retrieved by the ECM)

<common>

     <id>Store100</id>

          <server-managed>NONE</server-managed>

          <user-registry type="USERADMIN">

               <params>

                    <param name="DefaultsFileLocation " value="config/system/XPDintegDefaultRoles.xml"</param>

                    <param name="UpdatesType " value="ECM"</param>

               </params>

          </user-registry>

...

</common>

Please, refer to section Expeditor integrator User access control for more information about the user access control management in Expeditor integrator.

Local Lotus Expeditor micro broker and micro broker bridge Configuration

The IBM Lotus Expeditor integrator is based on a small footprint Message Broker component (IBM Lotus Expeditor micro broker). This JMS capable messaging provider offers file-system persistence of messages and once-and-only-once delivery of messages.

The Messaging Service of the Expeditor integrator hides internals of the micro broker and the micro broker bridge from the Developer and Administrator. It also puts the messaging environment in a transactional context. A default configuration of the micro broker is provided in the XPDinteg.xml configuration file.

If connectivity to the messaging back-end is required (e.g. to IBM Message Broker or IBM MQ Server), the micro broker Bridge must be used and configured. A typical micro broker bridge configuration is provided in the Sample_XPDinteg.xml file (also provided in /samples/config directory).

Lotus Expeditor micro broker Configuration

The following table contains the Message Service default properties that are passed on to the micro broker during start-up of the Expeditor integrator. Please, refer to the next chapter for configuration settings which are required for connectivity to the back-end messaging system.

Note: Since the connectivity to the back-end messaging system/broker is a major application property, changes to the Messaging Service configuration should be carefully handled and require a re-start of the Expeditor integrator. Service configuration should be carefully handled and require a re-start of the Expeditor integrator. Either run an Expeditor integrator platform Reset (see chapter Starting, Stopping, Resetting Expeditor integrator) or set the <clean-start> option to true to inform the micro broker to re-create all queues and bridges. All remaining local messages will be deleted during this step! Make sure you set <clean-start> back to false in the XPDinteg.xml after the successful re-start of the platform!

Table 10: Messaging Service properties (Lotus Expeditor micro broker)

Category	Property	Value (sample values / save your values here)	Re-start	Comment
<core *General Setting*
	<name>	mbroker_XPDinteg3000	No	Unique name of the local micro broker instance
	<port>	1883	Yes	Local communication port of the micro broker (make sure this is not blocked by any local Firewall).
	<clean-start>	false	No	This indicates whether the micro broker instance re-creates all queues and the bridge during runtime re-start (old messages and settings are discarded). This should be set to true when a configuration update to the micro broker / -bridge occurred. It must be *set back to false after successful re-start*.
	<max-message-size>	10000	Yes	micro broker max message size in KB (micro broker refuses messages larger then this value; recommendation is 2 MB)
	<max-queue-depth>	40000	No	Optional: max number of messages per local queue that can be stored (default = 40000)
	<persistence> <persistence-directory>	persistent/microbroker	Yes	Local directory where the micro broker stores its queue content persistently (should be not restored after from an old back-up!)
	<persistence> <log-size>	30000	Yes	micro broker transaction log size in KB (MBLog); must be smaller then MBStore
	<persistence> <object-store-size>	50000	Yes	Max size of the internal micro broker objects in KB (MBStore); must be larger then the *MBLog*
	<queuing> <dynamic-queue-creation>	true	Yes	Allow / disallow the creation of dynamic queues by connected micro broker JMS or MQTT clients. Static queues are those queues which are configured in this micro broker configuration section (see chapter 4.3.2 Default Queue Names). Dynamic queues can be created by any connected micro broker client. If only queues are allowed which are configured by Expeditor integrator (static queues), this parameter must be set to false (Note filed limitations in chapter 10.8 Blocking Dynaminc Queue Creation).
	<security><broker-listener> <port>	8883	Yes	Local secure TLS/SSL communication port of the micro broker (make sure this is not blocked by any local Firewall).
	<security><broker-listener> <mutual-authentication>	TRUE	Yes	Indicates whether mutual authentication during TLS/SSL session set-up is required or not (TRUE \| FALSE)
	<security><broker-listener> <keystore-location>	config/system/ssl/XPDinteg3000_KeyStore.jks	Yes	Name and path of the key store file used for TLS/SSL communication with messaging back-end (absolute or relative to Expeditor integrator installation directory)
	<security><broker-listener> <keystore-type>	JKS	Yes	Type of the key store file (JKS is default)
	<security><broker-listener> <keystore-password>	password	Yes	Password for accessing the key store (Note: Must be the same as the private key password if standard IBM JDK KeyManager is used!)
	<security><broker-listener> <truststore-location>	config/system/ssl/XPDinteg3000_TrustStore.jks	Yes	Name and path of the trust store file used for TLS/SSL communication with messaging back-end (absolute or relative to Expeditor integrator installation directory)
	<security><broker-listener> <truststore-type>	JKS	Yes	Type of the trust store file (JKS is default)
	<security><broker-listener> <truststore-password>	password	Yes	Password for accessing the trust store (Note: Must be the same as the private key password if standard IBM JDK KeyManager is used!)
	<security> <aclLocation>	config/system/micro-acl.xml	Yes	Name and location of the micro broker access control list configuration for messaging clients which access included IBM micro broker
	<security><authorization> <class>	default	Yes	Name of the used authorization class (default uses the shipped implementation)
	<security><authorization> <usersDefinitionFile>	config/system/XPDintegMBUsers.xml		Name and location of the file which contains messaging client user name / password list for accessing included micro broker (referenced in micro-acl.xml)
*JMS and client connection specific settings*
<connections>	<connections> <retry-interval>	60000	No	Property specifies in milliseconds how long a JMS client should wait for the message broker (here the local micro broker) to acknowledge requests before the client throws JMSExceptions. Default is 15000 milliseconds.
	<connections> <keepalive-duration>	60000	No	Optional property defines the time in msec after which the local micro broker will reset the connected (micro broker/JMS) clients if data traffic is idle.
	<connections> <jndikeyfactoryname>	jms/XPDinteg_ConnectionFactory	Yes	JNDI key which contains the name of the class that provides the Initial Context Factory (e.g.
*JNDI specific settings*
<jndi>	<jndi> <initial-context-factory>	com.ibm.pvc.jndi.provider.java.InitialContextFactory	Yes	Class name of initial context factory
	<jndi> <url>	local	Yes	Location of the JNDI (in the future, configuration information could be provided in a centrally managed JNDI)
	<jndi> <security-class>	com.ibm.rcp.integrator.messagingservice. impl.SampleJNDISecurity	Yes	Name of the JNDI security class that maintains the micro broker / -Bridge security settings
*Configuration for all local Expeditor integrator default queues*
<queues>	<queue purpose= <queue-name> <jndi-key>	“RequestInQueue” XPDinteg_ReqInQ jms/XPDinteg_ReqInQ	Yes	Local main *inbound* data queue where all incoming messages from the messaging back-end are received. The Dispatcher Svc moves the messages to local target queues for further processing
		“ResultOutQueue” XPDinteg_ResOutQ jms/XPDinteg_ResOutQ	Yes	Local main *outbound* data queue from which all outgoing messages are sent to the messaging back-end. The Dispatcher Svc moves messages from local queues to this queue for sending.
		“EventQueue” XPDinteg_EventQ jms/XPDinteg_EventQ	Yes	Local main *outbound* event queue from which all outgoing business events are sent to the messaging back-end Event Queue.
		“LogQueue” XPDinteg_LogQ jms/XPDinteg_LogQ	Yes	Local main *outbound* log queue from which all outgoing log events are sent to the messaging back-end Log Queue.
		“LocalDeadletterQueue” XPDinteg_LocalDeadletterQ jms/XPDinteg_LocalDeadletterQ	Yes	Local Deadletter queue where messages which can not be processed are moved to.
		“ServerDeadletterQueue” XPDinteg_ServerDeadletterQ jms/XPDinteg_ServerDeadletterQ	Yes	Local *outbound* Deadletter queue where messages which can not be processed are moved to in order to forward them to the DeadletterQ on the messaging back-end (This is configurable in the flow and activities.).
		“ControlQueue” XPDinteg_CtrlQ jms/XPDinteg_CtrlQ	Yes	Local *inbound* control message queue where all incoming control messages from the messaging back-end’s Control Queue are received for processing.
*Dispatcher destination queues*
<queue-name> <jndi-key>		XPDinteg_MsgToFtpQ jms/XPDinteg_MsgToFtpQ	Yes	Local inbound queue to which FileTransfer messages with TransportType = FTP are dispatched
		XPDinteg_MsgToSshQ jms/XPDinteg_MsgToSshQ	Yes	Local inbound queue to which FileTransfer messages with TransportType = SSH are dispatched
		XPDinteg_MsgToDBQ jms/XPDinteg_MsgToDBQ	Yes	Local inbound queue to which DBRecordUpdate/Select messages with TransportType = DB are dispatched
		XPDinteg_MsgToMsgQ jms/XPDinteg_MsgToMsgQ	Yes	Local inbound queue to which MessageForward messages with TransportType = MESSAGE are dispatched
		XPDinteg_MsgToFileSysQ jms/XPDinteg_MsgToFileSysQ	Yes	Local inbound queue to which FileTransfer messages with TransportType = FileSystemFile are dispatched
		XPDinteg_MsgToHttpQ jms/XPDinteg_MsgHttpQ	Yes	Local inbound queue to which HttpPost \| HttpGet \| HttpPut \| HttpDelete messages with TransportType = HTTP are dispatched
		XPDinteg_MsgToHttpsQ jms/XPDinteg_MsgHttpsQ	Yes	Local inbound queue to which HttpPost \| HttpGet \| HttpPut \| HttpDelete messages with TransportType = HTTPS are dispatched
		XPDinteg_MsgToReqQ jms/XPDinteg_MsgToReqQ	Yes	Local inbound queue to which all request messages are dispatched.
		XPDinteg_ScaleDataQ jms/XPDinteg_ScaleDataQ	Yes	*Optional. Retail-specific:* Local inbound queue to which FileTransfer messages with ResourceType = ScaleDataFile are dispatched
		XPDinteg_PrintLabelQ jms/XPDinteg_PrintLabelQ	Yes	*Optional. Retail-specific:* Local inbound queue to which FileTransfer messages with ResourceType = PrintLabelFile are dispatched
		XPDinteg_ShelfLabelQ jms/XPDinteg_ShelfLabelQ	Yes	*Optional. Retail-specific:* Local inbound queue to which FileTransfer messages with ResourceType = ShelfLabelFile are dispatched
		XPDinteg_FtpToMsgQ jms/XPDinteg_FtpToMsgQ	Yes	Local outbound queue to which FileTransfer messages with TransportType = FTP are dispatched
		XPDinteg_SshToMsgQ jms/XPDinteg_SshToMsgQ	Yes	Local outbound queue to which FileTransfer messages with TransportType = SSH are dispatched
		XPDinteg_FileSysToMsgQ jms/XPDinteg_FileSysToMsgQ	Yes	Local outbound queue to which FileTransfer messages with TransportType = LocalFileSystem are dispatched
		XPDinteg_HttpToMsgQ jms/XPDinteg_HttpToMsgQ	Yes	Local outbound queue to which HttpGet messages with TransportType = HTTP \| HTTPS are dispatched
*Configuration for all local XPD integrator default topics*
<topics>	<topic purpose= <topic-name> <jndi-key>	SampleTopic XPDinteg_SampleTopic XPDinteg_SampleTopic	Yes	Local topics for micro broker pub/sub (example configuration)

Listing 8 contains an example for the local LogQ configuration. The properties are saved in JNDI so that the configuration values could be centrally managed also.

Listing 8: micro broker queue configuration example (for local LogQ)

<messaging-service>

     <microbroker>

          <queues>

               <queue purpose="LogQueue">

                    <queue-name>XPDinteg_LogQ</queue-name>

                    <jndi-key>jms/XPDinteg_LogQ</jndi-key>

               </queue>

...

Default Queue Names (Section_3)

The following tables contain the default queue and topic names for Expeditor integrator.

Table 11: Local default queue names and topics for Expeditor integrator

JNDI keys used in default Expeditor integrator configuration <jndi-key>	Expeditor integrator default queue names <queue-name> / <topic-name>	Queue purpose Expeditor integrator
jms/XPDinteg_ReqInQ	XPDinteg_ReqInQ	Local queue for receiving all data messages from back-end
jms/XPDinteg_ResOutQ	XPDinteg_ ResOutQ	Local queue for sending all data messages to back-end
jms/XPDinteg_EventQ	XPDinteg_EventQ	Local queue for sending all (business) event messages to back-end
jms/XPDinteg_LogQ	XPDinteg_LogQ	Local queue for sending all log messages to back-end
jms/XPDinteg_LocalDeadletterQ	XPDinteg_LocalDeadletterQ	Local queue for un-processable messages
jms/XPDinteg_serverDeadletterQ	XPDinteg_ServerDeadletterQ	Local queue for messages which can not be processed and should be sent back to the originator (to the messaging server’s Deadletter queue)
jms/XPDinteg_CtrlQ	XPDinteg_CtrlQ	Local queue where control messages are received from back-end control queue
Internal default inbound queues (for Dispatcher service and performance tuning)
jms/XPDinteg_MsgToFtpQ	XPDinteg_MsgToFtpQ	Internal queue where data messages with MessagePurpose=FileTransfer and TransportType=FTP are dispatched to
jms/XPDinteg_MsgToSshQ	XPDinteg_MsgToSshQ	Internal queue where data messages with MessagePurpose=FileTransfer and TransportType=SSH are dispatched to
jms/XPDinteg_MsgToDBQ	XPDinteg_MsgToDBQ	Internal queue where data messages with MessagePurpose=DbRecordUpdate and TransportType=DB are dispatched to
jms/XPDinteg_MsgToFileSysQ	XPDinteg_ MsgToFileSysQ	Internal queue where data messages with MessagePurpose=FileTransfer and TransportType=LocalFileSystem are dispatched to
jms/XPDinteg_MsgToMsgQ	XPDinteg_MsgToMsgQ	Internal queue where data messages with MessagePurpose=MessageForward and TransportType=MESSAGE are dispatched to
jms/XPDinteg_MsgToHttpQ	XPDinteg_MsgToHttpQ	Internal queue where data messages with MessagePurpose=HttpPost \| HttpGet \| HttpPut \| HttpDelete and TransportType=HTTP are dispatched to
jms/XPDinteg_MsgToHttpsQ	XPDinteg_MsgToHttpsQ	Internal queue where data messages with MessagePurpose=HttpPost \| HttpGet \| HttpPut \| HttpDelete and TransportType=HTTPS are dispatched to
jms/XPDinteg_MsgToReqQ	XPDinteg_ MsgToReqQ	Internal queue where data Request messages are dispatched to (messages which trigger data capturing)
Optional retail default retail queues
jms/XPDinteg_ScaleDataQ	XPDinteg_ScaleDataQ	Internal retail-specific queue where data messages with ResourceType=ScaleDataFile are dispatched to
jms/XPDinteg_PrintLabelQ	XPDinteg_PrintLabelQ	Internal retail-specific queue where data messages with ResourceType=PrintLabelFile are dispatched to
jms/XPDinteg_ShelfLabelQ	XPDinteg_ShelfLabelQ	Internal retail-specific queue where data messages with ResourceType=ShelfLabelFile are dispatched to
Internal default outbound queues (for Dispatcher service and performance tuning)
jms/XPDinteg_FtpToMsgQ	XPDinteg_FtpToMsgQ	Internal queue where data messages with TransportType=FTP are dispatched to for sending to back-end messaging server
jms/XPDinteg_SshToMsgQ	XPDinteg_SshToMsgQ	Internal queue where data messages with TransportType=SSH are dispatched to for sending to back-end messaging server
jms/XPDinteg_FileSysToMsgQ	XPDinteg_FileSysToMsgQ	Internal queue where data messages with TransportType=LocalFileSystem are dispatched to for sending to back-end messaging server
jms/XPDinteg_HttpToMsgQ	XPDinteg_HttpToMsgQ	Local outbound queue to which HttpGet messages with TransportType = HTTP \| HTTPS are dispatched
Internal default pub / sub topic
jms/XPDinteg_SampleTopic	<topic-name> XPDinteg_SampleTopic	Example configuration for pub / sub message topic

Configuration of Back end Connectivity through Lotus Expeditor micro broker bridge

Configuration for connecting to Back-end messaging system

The connections between local queues in the Expeditor integrator and their corresponding queues on the back-end Message Broker can be configured independently per queue (for example, if the queues are located on different Message Broker machines). If only one back-end Message Broker is provided, all queues will be configured to communicate with this server.

First, the names of the remote queues are created and stored using JNDI. This way, queue names can be centrally managed (see Listing 9).
Second, Connection Factories must be configured which contain the physical connection settings to the back-end messaging system (e.g. hostname, IP address, port number etc., see Listing 10).
Third, these (remote) queue names must be linked to the local queue names which were also stored in JNDI in the micro broker configuration section (see Listing 8). The linkage is done through the micro broker Bridge pipe and flow definitions (see Table 13).

The remote queue names are stored in JNDI (see example for LogQ in Listing 9). The JNDI repository is locally provided at the moment, but could be replaced by a corporate JNDI repository for central management.

All configuration values for the Connection Factories and the back-end queue names are stored as <administered-objects>.

Listing 9: Example for JNDI name of messaging back-end LogQ (MQ Server queue name = LogQ)

<messaging-service>

     <microbroker>

          <jndi>

               <administered-objects>

               <queue purpose="ServerLogQueue" type="MQ" jndiKey="jms/MQ_ServerLogQ">

                    <params>

                         <param name="queue-name" value="LogQ"/>

                    </params>

               </queue>

…

There is a separate <connection-factory> for each messaging back-end server connection (MQ-Server). Possible configuration values are listed in Table 12.

Please, refer to chapter Connecting to additional Messaging Back-end Servers for the configuration of connections to multiple back-end messaging servers.

Listing 10: Lotus Expeditor micro broker bridge Connection Factory configuration example (place holder are in cursive)

<messaging-service>

     <microbroker>

          <jndi>

               <administered-objects>

                    <connection-factory name="MyConnectionFactory_1" type="MQ" jndiKey="jms/XPDinteg-MQConnectionFactory">

                         <params>

                              <param name="hostname" value="backbone_service_bus"/>

                              <param name="port" value="backbone_svc_bus_port"/>

                              <param name="queue-manager" value="MQ_backend_Q_manager"/>

                              <param name="channel" value="MQ_backend_srv_channel"/>

                              <!-- Optional for TLS/SSL enabled channel:

                              <param name="cipher-suite" value="SSL_RSA_WITH_RC4_128_SHA"/> -->

                              <param name="message-compression" value="RLE, ZLIBFAST,ZLIBHIGH"/>

                              <param name="header-compression" value="SYSTEM"/>

                              <param name="clientid" value="MQ_client_id"/>

                         </params>

                    </connection-factory>

                    <!-- Example for connection to other micro broker / Expeditor integrator instance: -->

                    <connection-factory name="MyConnectionFactory_2" type="MQTTJMS" jndiKey="jms/XPDinteg-DTSConnectionFactory">

                         <params>

                              <param name="hostname" value="9.153.166.28"/>

                              <param name="port" value="1883"/>

                         </params>

                    </connection-factory>

                    <!-- Example for connection to IBM WebSphere MQ server instance: -->

                    <connection-factory name="MyConnectionFactory_3" type="MQ" jndiKey="jms/XPDinteg-MyMQConnectionFactory">

                         <params>

                              <param name="hostname" value="mqserver.de.ibm.com"/>

                              <param name="port" value="1414"/>

                              <param name="channel" value="SYSTEM.DEF.SVRCONN"/>

                              <param name="queue-manager" value="XPDINTEGQM"/>

                              <param name="clientid" value="XPDinteg_3000"/>

                         </params>

                    </connection-factory>

Table 12: Connection properties for back-end messaging system connectivity (<connection-factory>)

Property	Value (examples)	Restart	Comment
<connection-factory name="ConnectionFactory1" type="MQ">
<hostname>	mqserver.ibm.com	Yes	IP address or hostname of the back-end MQ Server / Message Broker
<port>	14103	Yes	Port of the back-end MQ Server / Message Broker (default port = 1414)
<channel>	SYSTEM.DEF.SVRCONN	Yes	MQ Channel of the MQ Server / Message Broker This channel is configured with or without security at the MQ server. If it is TLS/SSL enabled channel the configuration for <cipher-suite> must be provided.
<cipher-suite>	SSL_RSA_WITH_RC4_128_SHA	Yes	Reference name of the cipher suite which is used for TLS/SSL communication if <channel> is configured as SSL channel. The reference names are defined in specific mapping tables (see note below). Note: The required TLS/SSL key and trust store location must be provided in the RCP platform configuration file (rcpinstall.properties, see chapter Enabling TLS/SSL communication to back-end messaging system).
<queue-manager>	XPDINTEGQM	Yes	Queue Manager MQ Server / Message Broker
<clientid>	User_0815	Yes	User account under which the micro broker Bridge connects as MQ client to the back-end MQ Server / Message Broker
<message-compression>	NONE, RLE, ZLIBFAST,ZLIBHIGH	Yes	This property activates channel compression for the message content. A list of compression types can be provided here, separated by a comma “,”. The finally used compression type is determined by the server (Note: There is no exception if compression is requested here, but not provided by the server.).
<header-compression>	SYSTEM or NONE	Yes	This property activates the channel compression for the message headers. Only a single value, “SYSTEM” or “NONE”, can be applied. Whether to use compression is determined by the server (Note: There is no exception if compression is requested here, but not provided by the server.).

Note: The names of JSSE CipherSuites specified in the XPDinteg.xml configuration file differ from their equivalent CipherSpecs used by the WebSphere MQ queue manager. Please find the mapping table under http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/topic/com.ibm.mq.csqzaw.doc/ja34740_.htm

WebSphere MQ channel compression support

Channel compression need to be activated on the MQ channel as well. Based on the settings on MQ server side and the provided setting for the Connectionfactory a compression algorithm is negotiated. Channel compression is support starting with MQ 7. On MQ 6 a certain fix level must be applied (http://www-01.ibm.com/support/docview.wss?uid=swg1IY95005).

MQ Channel properties example

Figure 7: MQ Channel properties example (Message compression set to ZLIBHIGH,Header compression set to System)

Supported compression algorithms are described here:

Message compression: http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/topic/com.ibm.mq.csqzae.doc/ic11670_.htm
Header compression: http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/topic/com.ibm.mq.csqzae.doc/ic11710_.htm

For validation purposes to check if compression is active, the following steps must be run on MQ side:

Activate channel monitoring on the queue manager (MEDIUM level is sufficient)
Start the command “runmqsc yourQMname”
Enter the command “display CHSTATUS (yourChannelName) ALL
Search for the values:
- COMPTIME and COMPRATE: they must display other values than zero
- MONCHL: must reflect the provided monitoring level
- COMPHDR: first value reflects the negotiated header compression algorithm, second value reflects the algorithm used for the last messages
- COMPMSG: first value reflects the negotiated message compression algorithm, second value reflects the algorithm used for the last messages

Further details can be found in the MQ info-center (http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp)

Bridging Expeditor integrator (micro broker) to messaging backends

Each Connection Factory consists of Pipes which again contain Flows. The Pipe definition specifies the required SyncQ and DeadletterQ at the messaging back-end server to which the Connection Factory is pointing (see Listing 11).

Listing 11: Pipe definition example (assigned to Connection Factory with JNDI key jms/XPDinteg-MQConnectionFactor, see Listing 10, and to JNDI keys of configured back-end SyncQ and DeadletterQ, also see LogQ example in Listing 9).

<pipe name="Back-end-pipe1">

     <jndi-connection connection-factory-key="jms/XPDinteg-MQConnectionFactory" sync-queue-key="jms/MQ_SyncQ" dead-letter-queue-key="jms/MQ_ServerDeadletterQ"/>

     <flow name=”…

…

     </flow>

…

Flows define the mapping of the local queue to the remote queue on the back-end messaging server. There are

INBOUND Flows for connections back-end -> XPDinteg
OUTBOUND Flows for connections Expeditor integrator -> back-end (see example in Listing 12).

Listing 12: micro broker bridge Flow configuration example for Log queue (local queue name = XPDinteg_LogQ see Listing 8, remote queue name = jms/MQ_LogQ, see Listing 9)

<messaging-service>

     <bridge>

          <pipes>

               <pipe name="Back-end-pipe1">

...

               <!-- Direction is INBOUND|OUTBOUND -->

               <flow name="logQFlow" direction="OUTBOUND">

                    <!-- The source and target types map onto the destination definitions in the bridge. -->

                    <source name="ubQ" type="QUEUE">

                         <value>XPDinteg_LogQ</value>

                    </source>

                    <target name="mqQ" type="JNDI" value="jms/MQ_LogQ"></target>

               </flow>

...

The following table contains possible configuration values for the micro broker bridge (see Table 13).

Table 13: Messaging Service properties (micro broker bridge)

Property	Value (save your values here)	Restart	Comment
General Bridge configuration
<bridge dynamic-pipes=	false	Yes	Allows [true] or disallows [false] dynamic creation of pipes.
Pipe and Flow configuration values
<pipe name=	Back-end-pipe1	Yes	name of the pipe
<jndi-connection connection-factory-key=	"jms/XPDinteg-MQConnectionFactory" sync-queue-key="jms/MQ_SyncQ" dead-letter-queue-key="jms/MQ_ServerDeadletterQ"	Yes	JNDI key for connection factory (MQ or MQTT connection). The JNDI key must match the configured bridge connection factory JNDI key in Listing 10, e.g. <connection-factory name="MyConnectionFactory_1" type="MQ" jndiKey="jms*/XPDinteg-MQConnectionFactory*">
<flow name=" direction=	"myflow" "INBOUND" \| "OUTBOUND"	Yes	Flow name Flow direction (INBOUND: back-end -> XPDinteg) The source and target types map onto the destination definitions in the bridge
<source name>= type=	"mqQ" "JNDI" jms/MyQueue	Yes	Definition of the source queue (JNDI key and queue type), e.g. on the back-end server for INBOUND
<target= nametype=	"ubQ" "QUEUE" value="XPDinteg_CtrlQ"	Yes	Definition of the destination (JNDI name and queue type), e.g. on Expeditor integrator for INBOUND

Note: The Expeditor micro broker bridge can be operated in different modes (transmission control policies). By default, the bridge uses Always connected connection policy. This means that the bridge tries to stay connected all the time to the MQ-based back-end messaging system. In case of connection failures, the bridge attempts to reconnect every 30 seconds.

More transmission control policy details of the micro broker bridge are currently not exposed for customization.

The availability of connections to the configured back-end messaging systems can be checked with the Expeditor integrator GUI. For this, the connection information is retrieved from the XPDinteg.xml configuration file. The Overview Page and the Monitoring Tool of the Expeditor integrator GUI provide a status overview of all configured Adapters and the back-end connections (configured bridge pipes).

(Please, refer to Expeditor integrator Graphical User Interface for the available GUI functions.)

If the Expeditor integrator GUI is not installed, the following commands are available in the OSGi console window for checking the back-end connectivity and Application Control Flow statistics:

Resource Adapter status:
checkadapterstatus <adaptername>
(<adaptername> is the name of the configured Resource Adapter in the XPDinteg.xml)
Messaging Server status:
checkmsgserverstatus <pipename>
(<pipename> is the name of the configured micro broker bridge pipe in the XPDinteg.xml)

(More Expeditor integrator console commands can be found in section Expeditor integrator console commands . Please, refer to chapter Starting, Stopping, Resetting Expeditor integrator for starting Expeditor integrator in Console mode.)

Enabling TLS/SSL communication to back-end messaging system

Connections to messaging back-ends can be secured by using TLS/SSL if the connection channel of the back-end is TLS/SSL enabled. Expeditor integrator requires

a key store with its private certificate which is trusted by the messaging back-end (contained in back-end’s trust store)
a trust store with trusted certificates of communication partners (e.g. back-end messaging system’s certificate and/or certificate-authorities)
the type of the used cipher suite

The location, the type and the password of the key and trust store must be provided to Expeditor integrator in the RCP configuration file rcpinstall.properties. Please, edit the

<XPDINTEG_HOME>/rcp/plugins/com.ibm.rcp.base_<version>/rcpinstall.properties

file and add the lines in following listing (see Listing 13).

Listing 13: Configuration lines in rcpinstall.properties for key and trust store location for TLS/SSL back-end connection

 # Key store location

-Djavax.net.ssl.keyStore=<pathto>/keystore_filename.jks

-Djavax.net.ssl.keyStoreType=JKS

-Djavax.net.ssl.keyStorePassword=kspassword

# Trust store location

-Djavax.net.ssl.trustStore=<pathto>/truststore_filename.jks

-Djavax.net.ssl.trustStoreType=JKS

-Djavax.net.ssl.trustStorePassword=tspassword

...

Note: The password of the key store and the stored private key (certificate) must be the same if IBM’s implementation of the KeyManager shipped with Expeditor integrator is used!
Changes to rcpinstall.propertiesrequire a platform RESET (see chapter Starting, Stopping, Resetting Expeditor integrator).

Connecting to additional Messaging Back end Servers

In environments where local Expeditor integrator queues must be connected to back-end queues which are spread over several back-end messaging servers, a

new <connection-factory> configuration,
new remote SyncQ and remote DeadletterQ definition,
new <flow> (<pipe>) for each local queue to back-end queue connection - must be created per additional back-end messaging server.

Listing 14 shows an example in which the local Expeditor integrator event queue is connected to its back-end EventQ placed on another message broker (Server2).

The local Expeditor integrator and the remote event queue are defined in the same way as the examples in Listing 8 and Listing 9 demonstrate. The JNDI references would be:

For the local event queue: XPDinteg_EventQ and
for the remote event queue: jms/MQ_EventQ.

Listing 14 : Configuration example for EventQ connection to additional back-end messaging server

<!-- Additional connection factory -->

     <connection-factory name="ConnectionFactory2" type="MQ" jndiKey="jms/XPDinteg-MQConnectionFactory-Server2">

     <params>

          <param name="hostname" value="ibm-msg-broker.ibm.com"/>

          <param name="port" value="1414"/>

          <param name="channel" value="SYSTEM.DEF.SVRCONN"/>

          <param name="queue-manager" value="XPDINTEGQM"/>

          <param name="clientid" value="XPDinteg_3000"/>

     </params>

...

<!-- New remote SyncQ and DeadletterQ settings for this connection -->

          <administered-objects> …

          <queue purpose="EventServerSyncQ" type="MQ" jndiKey="jms/MQ_SyncQ_Server2">

               <params>

                    <param name="queue-name" value="XPDINTEG.SyncQ"/>

               </params>

          </queue>

          <queue purpose="EventServerDeadletterQ" type="MQ" jndiKey="jms/MQ_DeadletterQ_Server2">

               <params>

                    <param name="queue-name" value="XPDINTEG.DeadletterQ"/>

               </params>

          </queue>

<!-- Example for remote EventQ for this connection -->

          <queue purpose="EventServerQ" type="MQ" jndiKey="jms/MQ_EventQ">

               <params>

                    <param name="queue-name" value="MQ.EventQ"/>

               </params>

          </queue>

          </administered-objects>

...

<!-- New pipe and flows for the EventQ -->

     <pipe name="Back-end-pipe-2">

          <jndi-connection connection-factory-key="jms/XPDinteg-MQConnectionFactory-Server2" sync-queue-key="jms/MQ_SyncQ_Server2" dead-letter-queue-key="jms/MQ_DeadletterQ_Server2"/>

               <flow name="eventQFlow" direction="OUTBOUND">

                    <source name="ubQ" type="QUEUE">

                         <value>XPDinteg_EventQ</value>

                    </source>

                    <target name="mqQ" type="JNDI" value="jms/MQ_EventQ"></target>

               </flow>

     </pipe>

Dispatcher Service Configuration (Section_14)

There are two options for incoming messages to be received and processed by Expeditor integrator:

Defintion of an inbound queue which is monitored by a JMS_DESTINATION_ADAPTER (see chapter ‎4.4.1 JMS Queue Destination Adapter).
Definition of an inbound queue which is pre-processed by the Expeditor integrator Dispatcher Service. The Dispatcher Service takes messages received at the defined inbound queue which is connected to external messaging systems by default and moves them to another internal queue depending on distinct JMS Custom Message Header properties.

The Dispatcher Service improves performance and availability of Expeditor integrator and allows for parallel processing of external messages received at a single inbound queue (see default queue set-up in Figure 2 in chapter ‎2.1.2 Queue configuration at Application Integration Back-end). The drawback is the introduced “transactional air gap”. The Dispatcher is not working in transactional context in order to gain the performance advantage.

This dispatching algorithm can be configured. Depending on the given JMS Custom Header properties, an incoming message can be moved to other local queue(s) for further processing (Please, refer to ‎Ref_2 for the JMS Custom Header definitions).
It is also configurable which Event Admin Service event for triggering a given ACS flow is fired when the dispatched message is moved to the configured target queue. This allows the Dispatcher being used very flexibly to forward incoming messages to custom target queues for further processing by custom ACS flows.
Figure 8 shows the default set-up of the Dispatcher Service. Depending on the JMS Custom Header properties MessagePurpose, TransportType and ResourceType, messages are dispatched to local Expeditor integrator queues for further processing.

Queue Dispatcher default set-up

Figure 8: Expeditor integrator Queue Dispatcher default set-up

The Dispatcher Service configuration is important for Expeditor integrators operations. Please, be very careful with the configuration and consult the Developer/Architect of the back-end message flow which creates the incoming messages for the Expeditor integrator in order to tune the provided default dispatching algorithm.

Listing 14 shows an example for the routing of an incoming File Transfer message which carries a file for the local file system and contains the following JMS Custom Message Header properties:

MessagePurpose=FileTransfer
TransportType=LocalFileSystem
ResourceType=ScaleDataFile

This message is received at a local queue with the JNDI key=jms/XPDinteg_ReqInQ and then put into the local destination queue with the JNDI key= jms/XPDinteg_ScaleDataQ. If the ResourceType is not set to ScaleDataFile, the File Transfer message with a local file system file will be moved to the default destination queue for the configured TransportType (e.g. for LocalFileSytem: jms/XPDinteg_MsgToFileSysQ).

Listing 15 also shows the new default dispatcher routing settings for incoming LocalFileSystem File Transfer messages.

Listing 15: Dispatcher Service configuration example for forwarding message with JMS Custom Headers set to MessagePurpose=”FileTransfer”, TransportType=”LocalfFileSystem” and ResourceType=”ScaleDataFile” (new schema introduced with version 6.2.2)

<dispatcher>

     <message>

          <microbroker-jndi-key>jms/XPDinteg_ConnectionFactory</microbroker-jndi-key>

               <microbroker-deadletterq-key>jms/XPDinteg_ServerDeadletterQ</microbroker-deadletterq-key>

                    <inbound>

                         <source jndi-key="jms/XPDinteg_ReqInQ" />

                         <destination>

                              <message-purpose value="FileTransfer">

                                   <build-timer enabled="true">

                                        <build-interval>60000</build-interval>

                                   </build-timer>

                                   <mapping>inbound</mapping>

                                        <transport-type value="LocalFileSystem">

                                             <!-- Retail specific in queue configuration -->

                                             <resource-types>

                                                  <resource-type value="ScaleDataFile">

                                                       <destinations>

                                                            <destination jndi-key="jms/XPDinteg_ScaleDataQ" <topic="com/ibm/integrator/flowtriggerevent/&lt;MessagePurpose&gt;/&lt;TransportType&gt;/&lt;ResourceType&gt;/dispatcher"/>

                                                       <!-- More target queues and trigger topics can be provided -->

…

                                                       </destinations>

                                                       <!-- Default target queue configuration -->

                                                       <default resource-type="LocalFileSystemFile">

                                                       <destinations>

                                                            <destination jndi-key="jms/XPDinteg_MsgToFileSysQ" topic="com/ibm/integrator/flowtriggerevent/&lt;MessagePurpose&gt;/&lt;TransportType&gt;/&lt;ResourceType&gt;/dispatcher"/>

                                                       </destinations>

Possible configuration parameters for the Expeditor integrator are listed in Table 14.

Table 14: Configuration values for Expeditor integrator Dispatcher Service

Property	Value	Comment
<build-interval>	60000	Default build timer in ms for files (Files can be transferred in concatenated FileTransfer messages. If the BuildTimer JMS Header property is set to -1, this default build-interval is used instead.)
<microbroker-jndi-key>	jms/XPDinteg_ConnectionFactory	JNDI key of used Connection Factory (definition of back-end messaging server connection; see Listing 10 in the section Configuration of Back-end Connectivity through Lotus Expeditor micro broker bridge)
<microbroker-deadletterq-key>	jms/XPDinteg_ServerDeadletterQ	JNDI key of DeadletterQ where non- dispatchable messages are moved to
<inbound>	<inbound \| outbound>	Dispatching direction Inbound: Back-end -> XPDinteg Outbound: Expeditor integrator -> Back-end
<source jndi-key=	e.g. "jms/XPDinteg_ReqInQ"	JNDI queue of dispatcher inbound queue (source queue)
<destination>		Definition of destination routing conditions and the destination queue
<message-purpose value=	"FileTransfer"	Routing condition: JMS Custom Header property MessagePurpose=FileTransfer
<*transport-type* value=	"LocalFileSystem"	Routing condition: JMS Custom Header property TransportType=LocalFileSystem
<*resource-type* value= <destination jndi-key= topic=	"ScaleDataFile" "jms/XPDinteg_ScaleDataQ"	Routing condition: JMS Custom Header property ResourceType=ScaleDataFile JNDI key of dispatching target queue if routing conditions are met Evend Admin Service topic which is fired after dispatching (to trigger a matching ACS flow (placeholders for values in JMS Custom Header properties are supported)
<default resource-type= <destination jndi-key= topic=	“LocalFileSystem” "jms/XPDinteg_MsgToFileSysQ"	Default destination configuration for given ResourceType JNDI key of LocalFileSystem default dispatching target queue Event Admin Service topic fired after dispatching the default ResourceType (placeholders for values in JMS Custom Header properties are supported)

Note the <build-interval> is the time period which the Dispatcher waits before issuing the flow trigger event in case of concatenated messages. After the expiration of the <build-interval>, the flow trigger event is issued to kick off the required ACS flow. The ACS Flow will then retrieve all the messages received so fare from the configured local in queue (e.g. MsgToFtpQ) and build the target file for FTP/SSH transfer or detachment to the local file system. Then the file transfer is done in append mode to include the high number of messages in a single file.

This allows for better tuning and performance handling if a large number of messages must be put into a single file on the target system (FTP/SSH/LocalFileSystem).

The fired Event Admin Service topic for triggering corresponding ACS flows can be configured with values of the message’s JMS Custom Message Header properties. The JMS Custom Header property name is used as placeholder in the topic configuration, e.g.:

<MessagePurpose> is the place holder for the value in the JMS Custom Header property MessagePurpose
<TransportType> is the place holder for the value in the JMS Custom Header property TransportType
<ResourceType> is the place holder for the value in the JMS Custom Header property ResourceType

Please, refer to ‎Ref_2 for more details.

Resource Monitor (Section 5) and Resource Adapter Configuration (Section 6)

The Resource Monitor keeps track of different resource types through a number of registered Resource Adapters. For the retail environment example in Figure 1 of chapter Solution Overview Example, the 4690 PoS Controller can only be accessed through its FTP Server. Since there might be different source FTP Servers for each file which is read from a FTP source directory, FTP access must be configured for each file that is handled. This means, there is a single FTP Resource Adapter required for each file resource (or a group of resources which can be identified through regular expressions).
Expeditor integrator supports monitoring of the following resource types:

Files and file groups (identifiable through regular expressions) on file servers which can be accessed through FTP, SSH (SCP) and on local file systems (XPDINTEG_FTP_ADAPTER, XPDINTEG_SSH_ADAPTER, XPDINTEG_FILE_SYSTEM_ADAPTER)
Database records which can be monitored through SQL SELECT statements using JDBC (XPDINTEG_DB_ADAPTER)
Local micro broker queues (XPDINTEG_JMS_DESTINATION_ADAPTER, XPDINTEG_JMS_LISTENER

In general, each Resource Adapter needs to be configured individually for each monitored resource. It takes configuration properties which define the condition under which the Resource Adapter informs the Resource Monitor about the existence of the monitored resource. Then, the Resource Monitor triggers an Event Admin event (Expeditor integrator Trigger Event) which can kick off Expeditor integrator Application Control Flows to process the identified resource or start other use case specific actions. ACS Flow Activities also use the Resource Adapter interface for accessing the identified resource (e.g. read/write a message or a file). Figure 8 shows that the JMS Destination Adapter is used by the Resource Monitor to identify new incoming messages. The published trigger event, which is also configurable under the Adapter configuration, kicks off the corresponding ACS Flow (that was configured for this trigger event, see ‎Ref_2). Then, the ACS Activities in the triggered flow can get hold of the triggering resource and process its data through the Resource Adapter’s Read/Write operations.

Resource Adapter configuration

Figure 9: Resource Adapter configuration to ACS Flow and Activities relationship

The Resource Monitor Service configuration is realized by providing a list of these Resource Adapters (one per resource) in the XPDinteg.xml configuration under the <resource-monitor-service> property. For each file handling action, a separate <adapter> configuration is provided that is associated with a certain Resource Adapter. Table 15 shows the generally available configuration properties for a Resource Adapter.

Table 15: General Resource Adapter configuration

Property	Explanation
<resource-monitor-service> <adapters> <adapter type=	Adapter Type; accepted values are: XPDINTEG_FTP_ADAPTER, XPDINTEG_SSH_ADAPTER, XPDINTEG_FILE_SYSTEM_ADAPTER, XPDINTEG_DB_ADAPTER, XPDINTEG_JMS_DESTINATION_ADAPTER, XPDINTEG_JMS_LISTENER_ADAPTER
<adapter name=	String: name of the adapter under which it is registered with the Resource Monitor
<listener> OR <polling>	Indicates method of operation. Either the adapter is synchronously polled by the Resource Monitor (<polling> ) or the adapter is able to provide new data on its occurrence asynchronously (<listener> ).
<interval>	Polling interval in milliseconds if method=<polling> (Note: Think about a sufficient value, see chapter 5.11.4 Reduce Apllication Load due to Polling)
<startup-delay>	Interval in milliseconds after which the adapter polling interval timer is started after Resource Adapter start. This helps to equalize the polling intervals of different adapters in order to achieve better load balancing.
<meta-data>	Any data structure that can be exchanged with the Resource Monitor (e.g. When using a listener, the message header property values could be provided as selection criteria here. When using the poll method for files, here the name and directory string of the file resource that is monitored is provided, e.g. meta-data:BINARY-/NWW_DAT/EAMMD743.MMS)
<topic>	Topic under which an event is created for the OSGi Event Admin Service in case the Resource Adapter retrieved data (Expeditor integrator Trigger Event: This event can trigger further actions, see flow definitions.)
<configuration> <param name= "JndiConnecitonFractoryKey" value =	JNDI lookup key for the name of the Connection Factory to which the monitored queue belongs to.
<param name= "JndiDestinationKey" value =	JNDI lookup key for the name of the monitored queue
<param name= "JndiDeadletterKey" value=	JNDI lookup key for the name of the used Deadletter queue (where message is moved to in case the received message is wrong)

The following chapters provide configuration details for these adapters.

JMS Queue Destination Adapter

The XPDINTEG_JMS_DESTINATION_ADAPTER is used to monitor local micro broker queues for incoming messages.

General format:

<adapter type="XPDINTEG_JMS_DESTINATION_ADAPTER" name="your_adapter_name">

     <!-- async mode -->

     <listener>

          <meta-data>jms_msg_header_property1 = 'value1'</meta-data>

          <topic> com/ibm/integrator/flowtriggerevent/<MessagePurpose>/MESSAGE/JmsAdapter</topic>

     </listener><configuration>

          <param name="JndiConnectionFactoryKey" value="your_connection_factory"/>

          <param name="JndiDestinationKey" value="your_monitored_queue"/>

          <param name="JndiDeadletterKey" value="your_deadletter_queue_if_msg_not_correct"/>

          <param name="ValidateLocationId" value="ON"/>

     </configuration>

</adapter>

Table 16: JMS Resource Adapter configuration

Property	Explanation
<adapter type>=	Adapter Type (monitors a given local queue) XPDINTEG_JMS_DESTINATION_ADAPTER
name=	String: name of the adapter under which it is registered with the Resource Monitor
<listener>	Indicates asynchronous operation: adapter is able to provide new data on its occurrence asynchronously
<meta-data>	Any data structure that can be exchanged with the Resource Monitor (when using a listener, the message header property values could be provided as selection criteria here.). If <meta-data> is not provided all messages will be picked up. If <meta-data>jms_msg_header_property1 = ''</meta-data>* all messages with JMS Custom Header property jms_msg_header_property1 are chosen (independent of its value).
<topic>	Topic under which an event is created for the OSGi Event Admin Service in case the Resource Adapter retrieved data (this event can trigger further actions, see flow definitions)
<configuration>	Tag which indicates detailed configuration parameter section
<param name= “JndiConnecitonFractoryKey” value=	JNDI lookup key for the name of the Connection Factory of the monitored queue.
<param name="JndiDestinationKey" value=	JNDI lookup key for the name of the monitored queue
<param name="JndiDeadletterKey" value=	JNDI lookup key for the name of the used Deadletter queue (where message is moved to in case the received message is wrong)
<param name="ValidateLocationId" value=	="ON" or "OFF" Describes whether adapter should check the JMS Custom Header parameter LocationId against the configured <common><id>my_location_id</id></common> value in XPDinteg.xml. If these are not the same, the message header is interpreted as invalid (Avoids processing of messges which might not have been intended for this Expeditor integrator runtime.). Note: default value is "OFF".

An example is given in Listing 16.

Listing 16: JMS_DESTINATION_ADAPTER example for messages received in jms/XPDinteg_CtrlQ with message header property MessagePurpose=ConfigUpdate and ResourceCmd=FILE

<adapter type="XPDINTEG_JMS_DESTINATION_ADAPTER" name="Default_ConfigUpdateResourceCmdAdapter">

     <!-- async mode -->

     <listener>

          <meta-data>MessagePurpose = 'ConfigUpdate' AND ResourceCmd LIKE 'FILE%'</meta-data>

          <topic>com/ibm/integrator/flowtriggerevent/ConfigUpdate/MESSAGE/JmsAdapter</topic>

     </listener>

     <configuration>

          <param name="JndiConnectionFactoryKey" value="jms/XPDinteg_ConnectionFactory"/>

          <param name="JndiDestinationKey" value="jms/XPDinteg_CtrlQ"/>

          <param name="JndiDeadletterKey" value="jms/XPDinteg_ServerDeadletterQ"/>

     </configuration>

</adapter>

JMS Listener Adapter

The XPDINTEG_JMS_LISTENER_ADAPTER is used to monitor local micro broker queues for incoming messages, dedicated to custom message forward flows.

General format:

<adapter type="XPDINTEG_JMS_LISTENER_ADAPTER" name="your_adapter_name">

     <!-- async mode -->

     <listener>

          <meta-data>jms_msg_header_property1 = 'value1'</meta-data>

          <topic> com/ibm/integrator/flowtriggerevent/<MessagePurpose>/MESSAGE/JmsAdapter</topic>

     </listener>

     <configuration>

          <param name="JndiTriggerMsgBackoutKey" value="your_queue_for_message_backout"/>

          <param name="JndiConnectionFactoryKey" value="your_connection_factory"/>

          <param name="JndiDestinationKey" value="your_monitored_queue"/>

          <param name="JndiDeadletterKey" value="your_deadletter_queue_if_msg_not_correct"/>

          <param name="ValidateLocationId" value="ON"/>

     </configuration>

</adapter>

Table 17: JMS Listener Adapter configuration

Property	Explanation
<adapter type>=	Adapter Type (monitors a given local queue) XPDINTEG_JMS_LISTNER_ADAPTER
name=	String: name of the adapter under which it is registered with the Resource Monitor
<listener>	Indicates asynchronous operation: adapter is able to provide new data on its occurrence asynchronously
<meta-data>	Any data structure that can be exchanged with the Resource Monitor (when using a listener, the message header property values could be provided as selection criteria here.). If <meta-data> is not provided all messages will be picked up. If <meta-data>jms_msg_header_property1 = ''</meta-data>* all messages with JMS Custom Header property jms_msg_header_property1 are chosen (independent of its value).
<topic>	Topic under which an event is created for the OSGi Event Admin Service in case the Resource Adapter retrieved data (this event can trigger further actions, see flow definitions)
<configuration>	Tag which indicates detailed configuration parameter section
<param name= “JndiTriggerMsgBackoutKey” value=	JNDI lookup name for the if the queue used for backing out messages (e.g. when the dedicated destination queue runs full).
<param name="CheckForDuplicateMessageIdsAfterRestart" value=	OPTIONAL: If message duplicate check after restart is required, this parameter has to be set to "TRUE" (Default: "FALSE". Duplicate check adds further overhead and should not be used if it's not required (e.g. when duplicates are already handled in the backend).
<param name= “JndiConnecitonFactoryKey” value=	JNDI lookup key for the name of the Connection Factory of the monitored queue.
<param name="JndiDestinationKey" value=	JNDI lookup key for the name of the monitored queue
<param name="JndiDeadletterKey" value=	JNDI lookup key for the name of the used Deadletter queue (where message is moved to in case the received message is wrong)
<param name="ValidateLocationId" value=	="ON" or "OFF" Describes whether adapter should check the JMS Custom Header parameter LocationId against the configured <common><id>my_location_id</id></common> value in XPDinteg.xml. If these are not the same, the message header is interpreted as invalid (Avoids processing of messges which might not have been intended for this Expeditor integrator runtime.). Note: default value is "OFF".

An example is given in Listing 17.

Listing 17: JMS_LISTENER_ADAPTER example for messages received in jms/XPDinteg_SourceQ with message header property MessagePurpose=CustomMsgForward.

<adapter type="XPDINTEG_JMS_LISTENER_ADAPTER" name="Custom_MsgForwardAdapter">

     <!-- async mode -->

     <listener>

          <meta-data>MessagePurpose = CustomMsgForward'</meta-data>

          <topic>com/ibm/integrator/flowtriggerevent/CustomMsgForward/JmsAdapter</topic>

     </listener>

     <configuration>

          <param name= “JndiTriggerMsgBackoutKey” value=”jms/XPDinteg_MsgBackoutQ”/>

          <param name="JndiConnectionFactoryKey" value="jms/XPDinteg_ConnectionFactory"/>

          <param name="JndiDestinationKey" value="jms/XPDinteg_SourceQ"/>

          <param name="JndiDeadletterKey" value="jms/XPDinteg_ServerDeadletterQ"/>

     </configuration>

</adapter>

FTP Resource Adapter

The XPDINTEG_FTP_ADAPTER is used to monitor a given file or list of files in a given directory on a provided FTP file server.

General format:

<adapter type="XPDINTEG_FTP_ADAPTER" name="your_adapter_name">

     <!-- sync mode -->

     <polling>

          <interval>your_polling_interval_in_msec</interval>

          <startup-delay>polling_interval_timer_startup_delay</startup-delay>

          <meta-data>FileTransferMode-monitored_file_name</meta-data>

          <topic>com/ibm/integrator/flowtriggerevent/FileTransfer/FTP/FtpAdapter</topic>

     </polling>

     <configuration>

          <param name="ResourceType" value="SampleFtpFile"/>

          <param name=…

...

     </configuration>

</adapter>

Table 18 provides an explanation of the available properties.

Table 18: FTP Resource Adapter configuration properties

Property	Explanation
<resourcAdapterType>=	Adapter Type (for accessing a given FTP Server) XPDINTEG_FTP_ADAPTER
name=	String: name of the adapter under which it is registered with the Resource Monitor
<polling>	Indicates synchronous operation (Resource Monitor polls this Adapter for the existence of the monitored resource)
<interval>	Polling interval in milliseconds if method=<polling> (Note: Think about a sufficient value, see chapter 5.11.4 Reduce Application Load due to Polling )
<startup-delay>	Interval in milliseconds after which the adapter polling interval timer is started after Resource Adapter start. This helps to equalize the polling intervals of different adapters in order to achieve better load balancing.
<meta-data>	It’s the name and directory string of the file resource that is monitored (e.g. <meta-data>BINARY-/NWW_DAT/EAMMD743.MMS) FILE_TRANSFER_MODE=BINARY or ASCII monitored_file_name=directory_name/filename OR a Regular Expression which identifies files due to a given search criteria (see chapter 4.4.5 Regular Expression Support for Local File System for details).
<topic>	Topic under which an event is created for the OSGi Event Admin Service in case the Resource Adapter retrieved the monitored file or data (this event can trigger further actions, see flow definitions)
<configuration> <param name=”ResourceType” value=	Resource Type corresponding to the Expeditor integrator settings. The Resource Type is mapped to a distinct file that needs to be transferred in the Resource Mapper configuration. This can also contain all access information for the FTP server (e.g. FTP server address, user name and password; see details about Resource Mapper configuration in chapter 4.6 Expeditor integrator Resource Mapper). If a ResourceType and Resource Mapper configuration is given the other <param name=…> parameters do NOT need to be provided here. (*)
<param name=”FtpServer” value=	Hostname of the remote FTP server
<param name=”FtpServerPort” value=	Port number of the FTP server port. By default this is 21, the traditional FTP server port
<param name=”FtpUser” value=	User name for login to the remote FTP server. This is mandatory.
<param name=”FtpPassword” value=	Password for the login to the remote FTP server. This is mandatory.
<param name=”BackupFtpServer” value=	Hostname of the backup FTP server. This server is used when the primary FTP server is not accessible.
<param=”BackupFtpServerPort” value=	Port number of the FTP server. By default this is 21, the traditional FTP server port,
<param name=”BackupFtpUser” value=	User name for login to the backup FTP server. This is mandatory if a backup FTP server is configured.
<param name=”BackupFtpPassword” value=	Password for login to the backup FTP server. This is mandatory if a backup FTP server is configured.
<param name=”FtpPassive” value=	TRUE \| FALSE Boolean indicator as to whether the FTP should be attempted in passive or active mode. Default is active, as per the FTP standard.
<param name=”FtpType" value=	FTP server type: DEFAULT \| 4690 DEFAULT for standard FTP server 4690 for FTP server of 4690 PoS controller This setting must be provided so that the adapter can use the correct command for enlisting files of the target directory. (Make sure that the DestinationPath is correctly provided, e.g. the 4690 type may understand the root path without a leading “/”, the DEFAULT server does require it.)
<param name=”DataTimeOut” value=	Optional parameter in msec which defines the data traffic idle time after which the resource adapter disconnects from the FTP server. Default: “-1” (not set) (This parameter was introduced to avoid the FTP connection thread to hang if no clean disconnecting from the FTP server was possible, e.g. during unexpected shutdown. Furthermore, it is recommended for unreliable FTP network environments to set the connection time out parameter on the FTP server as well.).
<param name="TransportType" value=	“FTP”
<param name="Description" value=	A description of the picked up file
<param name="TransferMode" value=	“ASCII” or “BINARY” In which mode is the picked up file resource transferred in the message’s payload (in ASCII or binary format)?
<param name="TransferConfirmationMode" value=	“DELETE” or “RecreateZero” or “WriteOtherFile” Defines the action on the picked up file resource after successful transfer to the back-end queue. NONE – leave the picked up file as it is (Note: With NONE, the file will trigger another transaction during the next polling interval!) DELETE – delete the file resource(s) in the source directory RecreateZero – recreate a file with length zero byte, but with the same name as the source file resource WriteOtherFile – source file is re-named with the name provided in WriteOtherFileName
<param name="WriteOtherFileName“ value=	String value with the file name in which the original transferred file should be re-named (if TransferConfirmationMode=WriteOtherFile). File is written into <XPDINTEG_HOME> if no path is included (e.g. value=”c:/backup/myfile_<TRANSID_8>.bkp”). The value of the Custom Message Header property DestinationName can also be used as file name with this place holder: <DestinationName>
<param name="FtpTempFileExtension“ value=	File name extension of the temporary file which is created in the given target directory (e.g. in DestinationPath) when a file is transferred/written to the FTP server. (e.g. value=”XPD”)
<param name “4690TestPermission” value=	TRUE or FALSE (default) Enables or disables a test write access to the 4690 target directory to which a file needs to be written or from where a file is to be removed. This procedure is recommended for environments where the 4690 Controller is configured as CC and DD cluster. The “4690TestPermission” file write test procedure ensures that Expeditor integrator has the correct access rights. This avoids a file being picked up in DD mode and being forwarded to the receiver process without being able to remove it (and therefore risc that it is picked up and sent again). It is recommended to choose larger polling intervals when the procedure is used to avoid SocketTimeOutExceptions of the FTP client. If insufficient access rights are recognized, the number of configured RetryAttempts is executed (parameter of the XPDINTEG_FILE_WRITE_TO_FTP activity configuration in ACS section of XPDinteg.xml). If all RetryAttempts have also failed due to insufficient access rights, the configured RollbackMessageAction option is performed (defined in ACS section of XPDinteg.xml: XPDINTEG_MESSAGE_TO_FILE and XPDINTEG_MESSAGE_READ activity parameters).
<param name "4690TestPermissionFilename" value=	Name of the file to be created for determining the file access permission rights on the IBM 4690 PoS controller. This value also contains the path and can be provided dynamically (e.g. value="<TRANSID_8>.TXT" would create a file name out of the last 8 digits of the transaction ID and the file extension .TXT, see Using the IBM Expeditor integrator platform for more dynamic file name creation options; ‎‎Ref_2).() Note: The test file name must be unique for each adapter**! Otherwise, race conditions will occur when additional adapters and flows try to write to the same target directory.
<param name="Encoding" value=	“UTF-8” or “UTF-16” etc. Type of data encoding.
<param name="FilePickupInterval" value=	value in milliseconds If more then one file needs to be processed (e.g. for the cases where a number of resources is selected using Regular Expressions, see chapter 4.4.5 Regular Expression Support for Local File System for details), the adapter waits this interval before the next matching resource is picked up. This avoids high peaks of RAM consumption and helps to achieve better load balancing.
<param name="ProcessZeroLengthFiles" value=	TRUE or FALSE By default all file related adapters (FileSytem, FTP and SSH) ignore the files with zero length. To process the zero length files, this adapter configuration parameter is used. If this value is set to TRUE, the adapter will also handle the zero length files.
<param name="TransferPriority" value=	e.g. “5” Option to provide custom transfer priority schema. Files with highest priority will be transferred to the back-end first.

(*) The param name="ResourceType" could be used to move FTP server access configuration values into the Expeditor integrator Resource Mapper configuration (e.g. FTP server name, port, user name). This makes the Resource Adapter configuration shorter and more readable. If configuration parameters are provided in the Resource Adapter configuration and in the Resource Mapper configuration, the Resource Adapter’s configuration is given priority over the Resource Mapper.
Please, refer to chapter ‎4.6 Expeditor integrator Resource Mapper Configuration for the Resource Mapper configuration.

(**) The param name=”4690TestPermission” and param name="4690TestPermissionFilename" were introduced due to limitations of the 4690 FTP server in conjunction with the FTP Client of Expeditor integrator. If the FileTransferConfirmation activity is used by the ACS flow which picks up the monitored FTP file on the 4690, sufficient file access rights must be given to Expeditor integrator. Since the file permissions can not be determined by the FTP client, a work around was implemented to enable the TransferConfirmationModes Delete and WriteOtherFile to determine the required file permissions on the source and target FTP directory. If these permissions can not be checked before the picked up file is sent of as message, it may not be possible to remove the source at the end of the flow (in the FileTransferConfirmation activity). In this case, the source file may be transferred again during the next adapter polling intervals.

An example is provided in Listing 18. The example adapter polls every minute the 4690 FTP directory for the sample.txt file. If sample.txt exists, and a FileTransfer ACS flow is triggered (by the configured trigger topic) the file will be picked up. If the used ACS flow contains the FileTransferConfirmation activity, the given configuration will create sample.txt_bkp for possible back up reasons. For this to be successful on 4690 FTP servers, the access rights to the 4690 directory are checked by the FileTransferConfirmation activity prior the transmission of the picked up file. This approach was chosen to avoid sending of the picked up file when being unable to remove the source file sample.txt.

It is recommended to configure the polling interval carefully (large enough, e.g. in minutes) due to the time delay the 4690 test permission procedure adds to the complete flow execution. Otherwise SocketTimeOutExceptions may be experienced

Listing 18: XPDINTEG_FTP_ADAPTER example

<adapter type="XPDINTEG_FTP_ADAPTER" name="SampleFtpAdapter">

     <!-- sync mode -->

     <polling>

          <interval>60000</interval>

          <meta-data>BINARY-sample.txt</meta-data>

          <topic>com/ibm/integrator/flowtriggerevent/FileTransfer/FTP/FtpAdapter</topic>

     </polling>

     <configuration>

          <param name="ResourceType" value="SampleFtpFile"/>

          <param name="TransferConfirmationMode" value="WriteOtherFile"/>

          <param name="WriteOtherFileName" value="sample.txt_bkp"/>

          <param name="FtpType" value="4690"/>

          <param name="4690TestPermissionFilename" value="sample.txt_test"/>

     </configuration>

</adapter>

Transactional roll-back behavior: The file transferal activities are rolled back in case of errors (e.g. number of transfer retries is exceeded and only parts of a file could be written). This does include the file creation process only. Created directories will be not removed during roll-back anymore.

If Expeditor Integrator is installed on a host running Red Hat Enterprise Linux, additional configuration steps might be required in order to avoid problems when using the FTP adapter. Please refer to chapter FTP connection issue on Red Hat Enterprise Linux for further configuration steps.

SSH Resource Adapter

The XPDINTEG_SSH_ADAPTER is used to monitor a given file or list of files in a given directory on a provided file server which can be accessed through the Secure Shell (SSH) of SSH servers.

The Expeditor integrator implementation is based on the two underlying protocols of the SSH server.

SFTP (Secure FTP on top of SSH)
SCP (Secure Copy)

The SFTP protocol specification gives the full control to perform various operations on SSH servers including file read and file write operation, where as SCP is meant only for secure file copy in both the directions. The other operations that are very important to this adapter are deleting files, renaming files, moving files, finding the directory existence, listing the files and so on.
The SFTP specification has direct support to perform the above operations where as the SCP does not. To perform the above operation, the SSH execution channel is used to run various commands and get the status of the operation (e.g. the result of the command).
Note: It is assumed that all Linux commands work on the accessed SSH servers. Linux commands are used to perform various operations. The format of the listed files follows the same format as the Linux ls command.

General format:

<adapter type="XPDINTEG_SSH_ADAPTER" name="your_adapter_name">

     <!-- sync mode -->

     <polling>

          <interval>your_polling_interval_in_msec</interval>

          <startup-delay>polling_interval_timer_startup_delay</startup-delay>

          <meta-data>FileTransferMode-monitored_file_name</meta-data>

          <topic>com/ibm/integrator/flowtriggerevent/FileTransfer/SSH/SshAdapter</topic>

     </polling>

     <configuration>

          <param name="ResourceType" value="SampleSshFile"/>

          <param name=…

...

     </configuration>

</adapter>

Table 19 provides an explanation of the available properties.

Table 19: SSH Resource Adapter configuration properties

Property	Explanation
<resourcAdapterType>=	Adapter Type (for accessing a given SSH Server) XPDINTEG_SSH_ADAPTER
name=	String: name of the adapter under which it is registered with the Resource Monitor
<polling>	Indicates synchronous operation (Resource Monitor polls this Adapter for the existence of the monitored resource)
<interval>	Polling interval in milliseconds if method=<polling> (Note: Think about a sufficient value, see chapter 5.11.4 Reduce Application Load due to Polling)
<startup-delay>	Interval in milliseconds after which the adapter polling interval timer is started after Resource Adapter start. This helps to equalize the polling intervals of different adapters in order to achieve better load balancing.
<meta-data>	It’s the name and directory string of the file resource that is monitored (e.g. <meta-data>BINARY-/NWW_DAT/EAMMD745.MMS) FILE_TRANSFER_MODE=BINARY or ASCII monitored_file_name=directory_name/filename OR a Regular Expression which identifies files due to a given search criteria (see chapter 4.4.5 Regular Expression Support for Local File System for details).
<topic>	Topic under which an event is created for the OSGi Event Admin Service in case the Resource Adapter retrieved the monitored file or data (this event can trigger further actions, see flow definitions)
<configuration> <param name=”ResourceType” value=	Resource Type corresponding to the Expeditor integrator settings. The Resource Type is mapped to a distinct file that needs to be transferred in the Resource Mapper configuration. This can also contain all access information for the SSH server (e.g. SSH server address, user name and password; see details about Resource Mapper configuration in chapter 4.6 Expeditor integrator Resource Mapper Configuration). If a ResourceType and Resource Mapper configuration is given the other <param name=…> parameters do NOT need to be provided here.
<param name=”SshServer” value=	Hostname of the remote SSH server.
<param name=”SshUser” value=	User name for login to the remote SSH server. This is mandatory.
<param name=”SshPassword” value=	Password for the login to the remote SSH server. This is mandatory.
<param name=”SshServerPort” value=	Port number of the SSH server port. By default this is 21, the traditional SSH server port
<param name=”SshType" value=	SSH server type: “SFTP” or “SCP”
<param name="TransportType" value=	“SSH”
<param name=”SshSessionTimeout”value=	SSH session timeout in milliseconds. (Default: 30000 = 30 seconds). Timout after which the SSH session is recognized as not available anymore.
<param name=”BackupSshServer” value=	Hostname of the backup SSH server. This server is automatically used when the primary SSH server is not accessible.
<param name=”BackupSshUser” value=	User name for login to the backup SSH server. This is mandatory if a backup SSH server is configured.
<param name=”BackupSshPassword” value=	Password for the login to the backup SSH server. This is mandatory if a backup SSH server is configured.
<param name=”BackupSshServerPort” value=	Port number of the backup SSH server. By default this is 22, the traditional SSH server port.
<param name=”BackupSshType” value=	Backup SSH server type: “SFTP” or “SCP”
<param name="Description" value=	A description of the picked up file
<param name="TransferMode" value=	“ASCII” or “BINARY” In which mode is the picked up file resource transferred in the message’s payload (in ASCII or binary format)?
<param name="TransferConfirmationMode" value=	“DELETE” or “RecreateZero” or “WriteOtherFile” Defines the action on the picked up file resource after successful transfer to the back-end queue. NONE – leave the picked up file as it is (Note: With NONE, the file will trigger another transaction during the next polling interval!) DELETE – delete the file resource(s) in the source directory RecreateZero – recreate a file with length zero byte, but with the same name as the source file resource WriteOtherFile – source file is re-named with the name provided in WriteOtherFileName.
<param name="WriteOtherFileName“ value=	String value with the file name in which the original transferred file should be re-named (if TransferConfirmationMode=WriteOtherFile). The value of the Custom Message Header property DestinationName can also be used as file name with this place holder: <DestinationName>
<param name="SshTempFileExtension“ value=	File name extension of the temporary file which is created in the given target directory (e.g. in DestinationPath) when a file is transferred/written to the SSH server. (e.g. value=”XPD”)
<param name="Encoding" value=	“UTF-8” or “UTF-16” etc. Type of data encoding.
<param name="FilePickupInterval" value=	value in milliseconds If more then one file needs to be processed (e.g. for the cases where a number of resources is selected using Regular Expressions, see chapter 4.4.5 Reduce Application Load due to Polling for details), the adapter waits this interval before the next matching resource is picked up. This avoids high peaks of RAM consumption and helps to achieve better load balancing.
<param name="ProcessZeroLengthFiles" value=	TRUE or FALSE By default all file related adapters (FileSytem, FTP and SSH) ignore the files with zero length. To process the zero length files, this adapter configuration parameter is used. If this value is set to TRUE, the adapter will also handle the zero length files.
<param name="TransferPriority" value=	e.g. “5” Option to provide custom transfer priority schema. Files with highest priority will be transferred to the back-end first.

The param name=”ResourceType” could be used to move SSH server access configuration values into the Expeditor integrator Resource Mapper configuration (e.g. SSH server name, port, user name). This makes the Resource Adapter configuration shorter and more readable. If configuration parameters are provided in the Resource Adapter configuration and in the Resource Mapper configuration, the Resource Adapter’s configuration is given priority over the Resource Mapper.
Please, refer to chapter ‎4.6 Expeditor integrator Resource Mapper Configuration for the Resource Mapper configuration.

An example for the configuration of the SSH Resource Adapter is given in Listing 19.

Listing 19: XPDINTEG_SSH_ADAPTER example

<adapter type="XPDINTEG_SSH_ADAPTER" name="SampleSshAdapter">

     <!-- sync mode -->

     <polling>

          <interval>60000</interval>

          <meta-data>BINARY-sample.txt</meta-data>

          <topic>com/ibm/integrator/flowtriggerevent/FileTransfer/SSH/SshAdapter</topic>

     </polling>

     <configuration>

          <param name="ResourceType" value="SampleSshFile"/>

     </configuration>

</adapter>

Transactional roll-back behaviour: The file transferal activities are rolled back in case of errors (e.g. number of transfer retries is exceeded and only parts of a file could be written). This does include the file creation process only. Created directories will be not removed during roll-back anymore.

File System Resource Adapter

The XPDINTEG_FILE_SYSTEM_ADAPTER is used to monitor a given file or list of files in a given directory of the local file system.

General Format:

<resource-monitor-service>

     <adapters>

          <adapter type="XPDINTEG_FILE_SYSTEM_ADAPTER" name="SampleFileSystemAdapter">

          <!-- sync mode -->

          <polling>

               <interval>your_polling_interval_in_msec</interval>

               <startup-delay>polling_interval_timer_startup_delay</startup-delay>

               <meta-data>FileTransferMode-monitored_file_name </meta-data>

               <topic>com/ibm/integrator/flowtriggerevent/FileTransfer/LocalFileSystem/LocalFileSystemAdapter</topic>

          </polling>

          <configuration>

               <param name="ResourceType" value="SampleFileSystemFile"/>

               <param name=…

…

          </configuration>

     </adapter>

Table 20 provides an explanation of the available properties.

Table 20: Local file system Resource Adapter configuration properties

Property	Explanation
<resourcAdapterType>=	Adapter Type (for accessing the local file system) XPDINTEG_FILE_SYSTEM_ADAPTER
name=	String: name of the adapter under which it is registered with the Resource Monitor
<polling>	Indicates synchronous operation (Resource Monitor polls this Adapter for the existence of the monitored resource)
<interval>	Polling interval in milliseconds if method=<polling> (Note: Think about a sufficient value, see chapter 5.11.4 Reduce Application Load due to Polling)
<startup-delay>	Interval in milliseconds after which the adapter polling interval timer is started after Resource Adapter start. This helps to equalize the polling intervals of different adapters in order to achieve better load balancing.
<meta-data>	It’s the name and directory string of the file resource that is monitored (e.g. <meta-data>BINARY-/NWW_DAT/EAMMD745.MMS) FILE_TRANSFER_MODE=BINARY or ASCII monitored_file_name=directory_name/filename OR a Regular Expression which identifies files due to a given search criteria (see chapter 4.4.5 Regular Expression Support for Local File System for details).
<topic>	Topic under which an event is created for the OSGi Event Admin Service in case the Resource Adapter retrieved the monitored file or data (this event can trigger further actions, see flow definitions).
<configuration> <param name=”ResourceType” value=	Resource Type corresponding to the Expeditor integrator settings. The Resource Type is mapped to a distinct file that needs to be transferred in the Resource Mapper configuration. This can also contain all file transfer related information (e.g. TransferMode, TransferConfirmationMode; see details about Resource Mapper configuration in chapter 4.6 Expeditor integrator Resource Mapper Configuration). If a ResourceType and Resource Mapper configuration is given the other <param name=…> parameters do NOT need to be provided here.
<param name="TransportType" value=	“LocaFileSystem”
<param name="Description" value=	A description of the picked up file
<param name="TransferMode" value=	“ASCII” or “BINARY” In which mode is the picked up file resource transferred in the message’s payload (in ASCII or binary format)?
<param name="TransferConfirmationMode" value=	“DELETE” or “RecreateZero” or “WriteOtherFile” Defines the action on the picked up file resource after successful transfer to the back-end queue. NONE – leave the picked up file as it is (Note: With NONE, the file will trigger another transaction during the next polling interval!) DELETE – delete the file resource(s) in the source directory RecreateZero – recreate a file with length zero byte, but with the same name as the source file resource WriteOtherFile – source file is re-named with the name provided in WriteOtherFileName.
<param name="WriteOtherFileName“ value=	String value with the file name in which the original transferred file should be re-named (if TransferConfirmationMode=WriteOtherFile) The value of the Custom Message Header property DestinationName can also be used as file name with this place holder: <DestinationName>
<param name="LocalTempFileExtension“ value=	File name extension of the temporary file which is created in the given target directory (e.g. in DestinationPath) when a file is transferred/written to the local file system. (e.g. value=”XPD”)
<param name="Encoding" value=	“UTF-8” or “UTF-16” etc. Type of data encoding.
<param name="FilePickupInterval" value=	value in milliseconds If more then one file needs to be processed (e.g. for the cases where a number of resources is selected using Regular Expressions, see chapter 4.4.5 Regular Expression Support for Local File System for details), the adapter waits this interval before the next matching resource is picked up. This avoids high peaks of RAM consumption and helps to achieve better load balancing.
<param name="ProcessZeroLengthFiles" value=	TRUE or FALSE By default all file related adapters (FileSytem, FTP and SSH) ignore the files with zero length. To process the zero length files, this adapter configuration parameter is used. If this value is set to TRUE, the adapter will also handle the zero length files.
<param name="TransferPriority" value=	e.g. “5” Option to provide custom transfer priority schema. Files with highest priority will be transferred to the back-end first.

The param name=”ResourceType” could be used to move the <param name=…> configuration values into the Expeditor integrator Resource Mapper configuration (e.g. TransferMode, TransferConfirmationMode). This makes the Resource Adapter configuration shorter and more readable. If configuration parameters are provided in the Resource Adapter configuration and in the Resource Mapper configuration, the Resource Adapter’s configuration is given priority over the Resource Mapper.
Please, refer to chapter 4.6 Expeditor integrator Resource Mapper Configuration for the Resource Mapper configuration.

Listing 20 shows an example for the XPDINTEG_FILE_SYSTEM_ADAPTER configuration

Listing 20: Example for a local file system adapter which polls the datatrans/outbound directory for the XPDinteg_sample.txt ASCII file every minute and fires the event with the com/ibm/integrator/flowtriggerevent/FileTransfer/LocalFileSystem/LocalFileSystemAdapter topic when the file appears.)

<resource-monitor-service>

     <adapters>

          <adapter type="XPDINTEG_FILE_SYSTEM_ADAPTER" name="SampleLocalFileSystemAdapter">

               <!-- async mode -->

               <polling>

                    <interval>60000</interval>

                    <meta-data>ASCII-datatrans/outbound/XPDinteg_sample.txt</meta-data>

                    <topic>com/ibm/integrator/flowtriggerevent/FileTransfer/LocalFileSystem/LocalFileSystemAdapter</topic>

               </polling>

          <configuration>

               <param name="ResourceType" value="SampleFileSystemFile2"/>

          </configuration>

     </adapter>

...

Regular Expression Support for Local File System/FTP Adapters/SSH Adapters

Local File System, FTP and SSH adapters use the property <meta-data> to poll for their respective resources. The property is used as following:

<meta-data> for polling
- A single file or a list of files to search for within the given directory.
- Format:
  <meta-data>:<FileTransferMode>-[REGEX-]<dir-name>/<file-name or regular-expr>
  <FileTransferMode> – either ASCII or BINARY; mandatory parameter.
  [REGEX-] – Keyword used to indicate that the adapter polls for multiple resources using the regular expression.
  
  <dir-name> - The directory name separated by ‘/’s
  
  <file-name or regular-expr> - A single file name or a regular expression supported by the java.util.regex API. If it’s a regular expression, [REGEX-] keyword should be used and the adapter specific property ‘SortOrder’ should be specified.
  For example:
  . - returns any character which may or may not be the line terminator
  * - returns any character sequence
  (If it is searched for the character . or *, these must be escaped, e.g. \. - escaped . would specifically search for .)
  More information on writing regular expressions can be found here: http://java.sun.com/docs/books/tutorial/essential/regex/index.html.
- Examples:
  <meta-data>BINARY-C:/NWW_DAT/EAMMDGUT.DAT</meta-data>
  - retrieves binary file EAMMDGUT.DAT
  
  <meta-data>ASCII-C:/NWW_DAT/EAMMDGUT.DAT</meta-data>
  
  <meta-data>BINARY-REGEX-C:/NWW_DAT/([A-Z])*\.DAT</meta-data>
  - retrieves all files in directory C:\NWW_DAT\ which consist of names out of characters A-Z with .DAT extension.
  
  <meta-data>ASCII-REGEX-C:/NWW_DAT/EAMMDGUT\.*</meta-data>
  - returns all files in directory c:\NWW_DAT\EAMMDGUT\
  
  <meta-data>ASCII-REGEX-/opt/import/.*Retail.*</meta-data>
  - returns all files in directory /opt/import which contain the string Retail.

adapter-specific properties
- SortOrder – can be either NAME, SIZE, TYPE or DATETIME. If nothing is specified, the default SortOrder is NAME. This parameter determines the order in which the files are sent (as messages) to the backend queue. This parameter is an Resource Adapter specific property for Local File System/FTP/SSH adapters and only valid when a regular expression is used for the file name in <meta-data>.
- SortDirection – can be either ASCENDING or DESCENDING. This parameter is only valid if the adapter polls for multiple resources using Regular Expressions. If nothing is specified, the default SortDirection is ASCENDING.

The following table shows the correlation between SortOrder and SortDirection.

Table 21: Regular expressions in File related Resource Adapters

SortOrder	SortDirection: ASCENDING	SortDirection: DESCENDING
NAME	General convention of sort: E.g., abc.txt appears before def.txt	General convention of sort: E.g., def.txt appears before abc.txt
SIZE	Smaller files first	Larger files first
TYPE	General convention of sort: E.g., f.abc appears before f.def	General convention of sort: E.g., f.def appears before f.abc
DATETIME	Older file first	Newer file first

Note:
1. The java.util.regex package defines the following characters as Metacharacters: ([{\^-$|]})?*+.
Care must be taken by the user to escape these characters in the XPDinteg.xml file. As the XPDinteg.xml adheres to java.util.Properties and as ‘\’ is an escape character for java.util.Properties, the Metacharacters need to be escaped using “\” (single ‘\’).
2. For avoiding complexity in representing regular expressions in XPDinteg.xml, ‘,’, ‘;’ and ‘\’ are never used as String literals in the regular expression for the file name, e.g., filenames having these characters cannot be polled.
3. When the SortOrder is “TYPE”, files without extension are picked up either first (if SortDirection is ASCENDING) or last (if SortDirection is DESCENDING).
4. If the file Resource Adapter process does not have appropriate access rights, the file operation will fail and the Application Control Flow is rolled back (Action is defined in parameter RollbackMessageAction in ACS configuration section).

Database Resource Adapter (JDBC Adapter)

The Expeditor integrator Database Resource Adapter allows for accessing databases through JDBC. IBM Lotus Expeditor integrator is shipped with a Derby database (see ‎Ref_10). This can be also used for use cases that require a database as data storage (rather then flat files). In addition, other JDBC-capable databases can also be accessed through the Database Resource Adapter (e.g. Oracle and DB2). The driver Java classes must be made available to the JDBC Adapter so that these additional databases can be used (‎Ref_2 “Using Expeditor integrator” contains samples on how Java driver classes for DB2 and Oracle can be integrated.)

Please, contact your IBM Sales Representative for a list of currently supported databases.

The Expeditor integrator Database Resource Adapter can access databases for reading records (select operation) as well as writing data records (insert, update, and delete operations). The Database Resource Adapter can also be used by the Resource Monitor for reporting the existence of given result set(s). For this, the adapter can be configured with complete SQL statements or with Expeditor integrator specific configuration values.
The <meta-data> parameter takes the search term (select statement) which specifies the result set for which the Database Adapter is polling. This can be either a simple where clause or a full SQL SELECT statement (see Table 21).

General Format:

<resource-monitor-service>

     <adapters>

          <adapter type="XPDINTEG_JDBC_ADAPTER" name="SampleAdapterForDatabase">

               <!-- sync mode -->

                    <polling>

                         <interval>your_polling_interval_in_msec</interval>

                         <startup-delay>polling_interval_timer_startup_delay</startup-delay>

                         <meta-data>your_table_name:your_where_clause OR SQL-your_sql_select_statement</meta-data>

                         <topic>com/ibm/integrator/flowtriggerevent/DBRecordSelect/DB/JDBCAdapter</topic>

                    </polling>

               <configuration>

                    <param name="DBURI" value="jdbc:derby:persistent/PersistentStore"/>

                    <param name="DRIVER_CLASS" value="org.apache.derby.jdbc.EmbeddedDriver"/>

                    <param name="USER" value="xpdinteg"/>

                    <param name="PASSWORD" value="xpdinteg"/>

Table 22 provides an explanation of the available properties.

Table 22: Database Resource Adapter configuration properties

Property	Explanation
<resourcAdapterType>=	Adapter Type (for accessing JDBC databases) XPDINTEG_DATABASE_ADAPTER
name=	String: name of the adapter under which it is registered with the Resource Monitor
<polling>	Indicates synchronous operation (Resource Monitor polls this Adapter for the existence of the monitored resource)
<interval>	Polling interval in milliseconds if {{method=}}} (Note: Think about a sufficient value, see chapter 5.11.4 Reduce Application Load due to Polling)
<startup-delay>	Interval in milliseconds after which the adapter polling interval timer is started after Resource Adapter start. This helps to equalize the polling intervals of different adapters in order to achieve better load balancing.
<meta-data>	Contains the SELECT statement which is used to monitor for a given result set either a) as where clause in the format *<tablename>:<where clause>* e.g. ORDERS:SKU=’TDL60S’ OR b) as SQL statement in the format *SQL-<Full SQL Statement>* e.g. SQL-SELECT * FROM ORDERS WHERE SKU=’TDL60S’
<topic>	Topic under which an event is created for the OSGi Event Admin Service in case the Resource Adapter retrieved the monitored file or data (this event can trigger further actions, see flow definitions).
<configuration> <param name="DBURI" value=	"your_db_access_uri" contains the valid JDBC database URI e.g. "*jdbc:derby:persistent/PersistentStore*" (access to XPDinteg’s persistence store in the local Derby database)
<param name="DRIVER_CLASS" value/>=	"your_db_jdbc_driver_name" provides the JDBC driver class name, e.g. "*org.apache.derby.jdbc.EmbeddedDriver*" for the included Derby database
<param name="USER" value=	"your_db_user_name"
<param name="PASSWORD" value=	"your_db_user_passwd"

An example configuration for the JDBC Adapter is given in Listing 21.

Listing 21: JDBC Adapter example configuration (which monitors table XPDINTEGBUSINESSEVENTS of the Expeditor integrator Derby database with the name PersistenceStore for the existence of records with TRANSACTION_ID='001' and fires the given trigger event)

<resource-monitor-service>

     <adapters>

          <adapter type="XPDINTEG_JDBC_ADAPTER" name="SampleAdapterForDatabase">

               <!-- sync mode -->

               <polling>

                    <interval>60000</interval>

                    <meta-data>XPDINTEGBUSINESSEVENTS:TRANSACTION_ID='001'</meta-data>

                    <!--

                    <meta-data>SQL-select * from XPDINTEGBUSINESSEVENTS WHERE TRANSACTION_ID='001'</meta-data>

-->

                    <topic>com/ibm/integrator/flowtriggerevent/DBRecordSelect/DB/JDBCAdapter</topic>

               </polling>

               <configuration>

                    <param name="ResourceType" value="TxId001Record"/>

                    <param name="DBURI" value="jdbc:derby:persistent/PersistentStore"/>

                    <param name="DRIVER_CLASS" value="org.apache.derby.jdbc.EmbeddedDriver"/>

                    <param name="USER" value="xpdinteg"/>

                    <param name="PASSWORD" value="xpdinteg"/>

               </configuration>

          </adapter>

...

After the Resource Monitor has triggered an ACS Flow for interacting with the database (e.g. retrieve the reported result set and send it to the back-end system), the result set data structure is transformed into Expeditor integrators own internal XML data structure. Please, refer to the Using the IBM Expeditor integrator platform for more details about this (see ‎Ref_2).

HTTP Outbound Adapter

The HTTP Adapter provides access to resources located on an HTTP server. Depending on the security model of the HTTP server, resources are

written (HTTP Put) ,
read (HTTP Get, which can be initiated by a local Resource Adapter which polls for a given resource or by a Request Message sent from the back-end)
updated (HTTP Post) or
deleted (HTTP Delete).

These resources can be files which are located on the directory of the HTTP server or any automatically created response (e.g. an XML stream created by CGI scripts). It is important to configure the Expeditor integrator HTTP Adapter appropriately to address the different resources. Currently, only binary objects and XML structures which comply with Expeditor XPDINTEG_DB_XML are supported.

Since the HTTP Adapter is based on the Apache client, all Apache compliant HTTP servers should be accessible. Expeditor integrator is supported on:
Apache HTTP Server v2.2 with

HTTP and HTTPs
HTTP Authentication methods:
- HTTP Basic Authentication
- Digest Access Authentication

The XPDINTEG_HTTP_ADAPTER is used to monitor a given resource on a provided HTTP server (e.g. file or list of files in a given directory).

General format:

<adapter type="XPDINTEG_HTTP_ADAPTER" name="your_adapter_name">

     <!-- sync mode -->

     <polling>

          <interval>your_polling_interval_in_msec</interval>

          <startup-delay>polling_interval_timer_startup_delay</startup-delay>

          <meta-data>ASCII-/absolut_path_and_name_of_monitored_file</meta-data>

          <topic>com/ibm/integrator/flowtriggerevent/HttpGet/HTTP/HttpAdapter</topic>

     </polling>

     <configuration>

          <param name="HeadMethodSupported" value="true"/>

          <param name="ResourceType" value="SampleHttpFile"/>

          <param name=…

...

     </configuration>

</adapter>

Table 23 provides an explanation of the available properties.

Table 23: HTTP Resource Adapter configuration properties

Property	Explanation
<ResourcAdapterType>=	Adapter Type (for accessing a given HTTP Server) XPDINTEG_HTTP_ADAPTER
name=	String: name of the adapter under which it is registered with the Resource Monitor
<polling>	Indicates synchronous operation (Resource Monitor polls this Adapter for the existence of the monitored resource)
<interval>	Polling interval in milliseconds if method=<polling> (Note: Think about a sufficient value, see chapter 5.11.4 Reduce Application Load due to Polling)
<startup-delay>	Interval in milliseconds after which the adapter polling interval timer is started after Resource Adapter start. This helps to equalize the polling intervals of different adapters in order to achieve better load balancing.
<meta-data>FILE_TRANSFER_MODE-/relative_path_and_name_of_the_monitored_file_name </meta-data>	FILE_TRANSFER_MODE=BINARY or ASCII; monitored_file_name=/directory_name/filename It’s the name and directory string of the resource or directory that is monitored (requires a ‘/’ at the beginning! e.g. <meta-data>ASCII-/*NWW_DAT/EAMMD743.MMS</meta-data>). The path variable is usually the relative path from the HTTP servers htdocs directory (e.g. if c:\apache\htdocs\myfiles\sample.txt* needs to be picked up, meta data should look like this: <meta-data>ASCII-/myfiles/sample.txt</meta-data>) If this is a complete URL which also contains the HTTP server name and port, the HttpServer, HttpServerPort and TransportType parameters are overwritten. Note: This is different to the configuration of the other File Adapters.
<topic>	Topic under which an event is created for the OSGi Event Admin Service in case the Resource Adapter retrieved the monitored file or data (this event can trigger further actions, see flow definitions)
<configuration> <param name=”ResourceType” value=	Resource Type corresponding to the Expeditor integrator settings. The Resource Type is mapped to a distinct resource (e.g. file) that needs to be transferred in the Resource Mapper configuration. This can also contain all access information for the HTTP server (e.g. HTTP server address, user name and password; see details about Resource Mapper configuration in chapter 4.6 Expeditor integrator Resource Mapper Configuration). If a ResourceType and Resource Mapper configuration is given the other <param name=…> parameters do NOT need to be provided here.
<param name="HeadMethodSupported" value=	“true” \| “false” “true” – target HTTP server supports HTTP HEAD method (default value) “false” – target HTTP server does NOT support HEAD method Indicates whether the HTTP HEAD method is supported by the target HTTP Server or not. The HTTP standard requires the HEAD method and polling using this method is more efficient, but some HTTP servers (mostly in embedded devices) may not have HEAD implemented.
<param name="ResourceAuthenticationType" value=	“NONE” \| “BasicAuth” \| “DigestAccessAuth” HTTP authentication method NONE – no authentication is required (default value) BasicAuth – HTTP Basic Authentication method DigestAccessAuth – HTTP Digest Access authentication method (encrypts password)
<param name="TransportType" value=	“HTTP” \|”HTTPS” default = “HTTP”
<param name=” HttpAcceptSelfSignedCertificates” value=	TRUE \| FALSE Allows for accepting self-signed certificates issued by the HTTP Server. TRUE – accept self-signed certificates (=DEFAULT) FALSE – don’t accept self-signed certificates (an officially by a CA signed certificate is allowed only)
<param name=”HttpServer” value=	Hostname or IP address of the remote HTTP server.
<param name=”HttpServerPort” value=	Port number of the HTTP server port. By default this is 80 for HTTP and 443 fo HTTPs, the traditional HTTP server ports.
<param name=”HttpUser” value=	User name for login to the remote HTTP server. This is mandatory for HTTP Basic and Digest Access Authentication.
<param name=”HttpPassword” value=	Password for the login to the remote HTTP server. This is mandatory for Basic and Digest Access. Password can be encrypted with the provided password utility tool (see PasswordUtil).
<param name="HttpMimeType" value=	Maps to HTTP header Content-Type, e.g. “text/plain”, “text/html” or “audio/mpeg” (see ‎Ref_28)
<param name="HttpUserAgent" value=	Maps to HTTP header property User-Agent, e.g. User-Agent: Mozilla/4.0
<param name="HttpVersion" value=	“HTTP/1.0” \| “HTTP/1.1” Maps to HTTP header property Protocol Version HTTP/1.0 - older version which opens a TCP connection for each request HTTP/1.1 – new version which allows the client to re-use an open TCP connection for more requests (persistent connection), requires Keep-Alive property (=DEFAULT)
<param name="HttpRetries" value=	Number of retries which the Apache HTTP client uses to access the HTTP server.
<param name="HttpServerProxy" value=	HTTP Proxy server name or IP address.
<param name="HttpServerProxyPort" value=	HTTP Proxy port. If HTTP server proxy is provided, the default port is 80.
<param name=”HttpServerProxyUser” value=	User name for login to the remote HTTP server proxy. This is mandatory if the HTT server proxy requires this.
<param name=”HttpServerProxyPassword” value=	Password for the login to the remote HTTP proxy. Password can be encrypted with the provided password utility tool (see PasswordUtil).
<param name=”HttpType" value=	“DEFAULT” Allows the definition of different HTTP server types. “DEFAULT” – default Apache v2.2 HTTP Server
<param name="Description" value=	A description of the picked up file
<param name="TransferMode" value=	“ASCII” or “BINARY” In which mode is the picked up HTTP resource transferred in the message’s payload (in ASCII or binary format)? This setting is retrieved out of the HTTP Reply header parameter Content-Type and is then mapped to the ResourceData header property TransferMode value ASCII or BINARY.
<param name="TransferConfirmationMode" value=	“DELETE” or “RecreateZero” or “WriteOtherFile” Defines the action on the picked up file resource after successful transfer to the back-end queue. NONE – leave the picked up file as it is (Note: With NONE, the file will trigger another transaction during the next polling interval!) DELETE – delete the (file) resource(s) in the source directory RecreateZero – recreate a file with length zero byte, but with the same name as the source file resource (creates an empty resource using HTTP PUT) WriteOtherFile – source file is re-named with the name provided in WriteOtherFileName (runs an HTTP DELETE and HTTP PUT operation with the new file name) (Note: Many HTTP servers are not configured for HTTP PUT/DELETE. The confirmation operation may be done by invoking a script or a servlet on the HTTP/Application Server instead. See "HttpTransferConfirmationOperation")
<param name="HttpTransferConfirmationOperation" value= <param name="HttpTransferConfirmationPostUri" value="<confirmation_uri>"	DELETE_PUT \| POST Allows for configuring the type of confirmation: DELETE_PUT is the default value and works equivalent to the file operations (first the resource is deleted using HTTP DELETE and then, in case of WriteOtherFile, written with HTTP PUT) POST provides an option to confirm the resource retrieval by invoking an URI which must be provided under FilePostUri (e.g. in case PUT and DELETE is not allowed). HttpTransferConfirmationPostUri is mandatory in this case!
<param name="WriteOtherFileName“ value=	String value with the file name in which the original transferred file should be re-named (if TransferConfirmationMode=WriteOtherFile)
<param name="Encoding" value=	“UTF-8” or “UTF-16” etc. Type of data encoding.
<param name="FilePickupInterval" value=	This is not applicable to HTTP/s transport (regular expressions are not supported).
<param name="ProcessZeroLengthFiles" value=	TRUE or FALSE By default all file related adapters (FileSytem, FTP, SSH, HTTP) ignore the files with zero length. To process the zero length files, this adapter configuration parameter is used. If this value is set to TRUE, the adapter will also handle the zero length files.
<param name="TransferPriority" value=	This is not applicable to HTTP/s transport since this only applies to multiple file transfer situations.
<param name=”MaxContentLength” value=	Maximum number of kilo bytes allowed for the length of a response message body. Default (10MB): 10000

The param name=”ResourceType” could be used to move HTTP server access configuration values into the Expeditor integrator Resource Mapper configuration (e.g. HTTP server name, port, user name). This makes the Resource Adapter configuration shorter and more readable. If configuration parameters are provided in the Resource Adapter configuration and in the Resource Mapper configuration, the Resource Adapter’s configuration is given priority over the Resource Mapper.
Please, refer to chapter ‎4.6.3 Default Resource Mapper Configuration for the Resource Mapper configuration.

An example is provided in Table 22.

Listing 21: XPDINTEG_HTTP_ADAPTER example

<adapter type="XPDINTEG_HTTP_ADAPTER" name="SampleMp3Adapter">

     <!-- sync mode -->

     <polling>

          <startup-delay>60000</startup-delay>

          <interval>60000</interval>

          <meta-data>BINARY-/sample.mp3</meta-data>

          <topic>com/ibm/integrator/flowtriggerevent/HttpGet/HTTP/SampleAdapter/HttpAdapter</topic>

     </polling>

     <configuration>

          <param name="HeadMethodSupported" value="true"/>

          <param name="ResourceType" value="SampleMp3File"/>

          <param name="TransportType" value="HTTPS"/>

          <param name="HttpServer" value="127.0.0.1"/>

          <param name="HttpServerPort" value=”443”/>

          <param name=”HttpAcceptSelfSignedCertificates” value="TRUE"/>

          <param name=”HttpUser” value="testuser"/>

          <param name=”HttpPassword” value="{xor}Jy87PjsyNjE\="/>

          <param name="HttpMimeType" value="audio/mpeg"/>

          <param name="HttpUserAgent" value="Mozilla/4.0"/>

          <param name="TransferConfirmationMode" value="DELETE"/>

          <param name="HttpTransferConfirmationMode" value="DELETE_PUT"/>

     </configuration>

</adapter>

Transactional roll-back behavior: The file transferal activities are rolled back in case of errors (e.g. number of transfer retries is exceeded and only parts of a file could be written). This does include the file creation process only. Created directories will be NOT removed during roll-back anymore.

After the Resource Monitor has triggered an ACS Flow for interacting with the HTTP target, the found HTTP resource (e.g. file) is retrieved and forwarded within a message to the back-end. Please, refer to the Using the IBM Expeditor integrator platform documentation for more details about this (see ‎Ref_2).

Generic Resource Adapter

The Generic Resource Adapters does not interact with any attached resource (<meta-data> is not used). In this case the polling interval can be used like a timer value. After each polling interval, trigger event with the configured <topic> will be fired.
An example for using the Generic Resource Adapter as timer is the House Keeping Adapter which periodically kicks of the House Keeping flow (see Listing 22).

Listing 22: Configuration example for the Generic Resource Adapter

...

     <adapter type="XPDINTEG_GENERIC_ADAPTER" name="SampleHouseKeepingAdapter">

          <!-- sync mode -->

          <polling>

               <interval>86400000</interval>

               <startup-delay>polling_interval_timer_startup_delay</startup-delay>

               <meta-data>NONE</meta-data>

               <topic>com/ibm/integrator/flowtriggerevent/HouseKeeping</topic>

          </polling>

     </adapter>

…

Other Adapters and Platform Access Options

This chapter explains other Adapters which are not only responsible for accessing a defined type of resource. The following adapters allow for data exchange with the Expeditor integrator runtime without using the messaging channel.

REST Adapter (Section_7)

Overview

The REST (REpresentational State Transfer) Adapter provides data access to the Expeditor integrator runtime through HTTP. In addition to the messaging channel access, the REST Adapter allows for exchanging message content with Expeditor integrator, but uses HTTP. This is important for the integration of other not-messaging-based legacy systems (e.g. terminals, PDAs).

Figure 10 shows the REST Adapter architecture. The HTTP Request is taken and transformed into an Expeditor integrator compliant message. This message is then placed into the ReqInQ or CtrlQ in the same way as the messaging system would do it. From there on, the previous HTTP request is handled in the same way as any incoming message. The process of the HTTP request message is tracked in the Persistence Service. This information is taken to provide an appropriate response to the initial HTTP Request.

REST Adapter Architecture Overview

Figure 10: REST Adapter Architecture Overview

Please, refer to the Using the IBM Expeditor integrator platform (‎Ref_2) for details about how the REST Adapter can be used for data exchange with Expeditor integrator.

REST Adapter Configuration

The configuration relevant parameters can be found in Listing 23. There, the Expeditor integrator standard configuration is given:

for the routing of the possible HTTP Request messages to the correct inbound queues,
for the mapping of the HTTP-Request-Header to the Expeditor integrator JMS Custom Header properties.

Note: The user name and password required for accessing the Web Container of Expeditor integrator is managed by the User Admin Service and is configured separately. The initial configuration is provided in the XPDintegDefaultRoles.xml file. This can be changed using the available Expeditor integrator configuration update mechanisms. Please, refer to section ‎8 for more details.

Listing 23: REST Adapter configuration example

<rest>

     <connectionFactory>jms/XPDinteg_ConnectionFactory</connectionFactory>

     <routing>

          <messagepurpose value="FileTransfer" destination="jms/XPDinteg_ReqInQ"/>

          <messagepurpose value="FileRequest" destination="jms/XPDinteg_ReqInQ"/>

          <messagepurpose value="BrowseDirectory" destination="jms/XPDinteg_CtrlQ"/>

          <messagepurpose value="ConfigRetrieval" destination="jms/XPDinteg_CtrlQ"/>

          <messagepurpose value="HouseKeeping" destination="jms/XPDinteg_CtrlQ"/>

          <messagepurpose value="ExecuteScript" destination="jms/XPDinteg_CtrlQ"/>

          <messagepurpose value="BrowseQueue" destination="jms/XPDinteg_CtrlQ"/>

          <messagepurpose value="ConfigUpdate" destination="jms/XPDinteg_CtrlQ"/>

          <messagepurpose value="DrainQueue" destination="jms/XPDinteg_CtrlQ"/>

          <messagepurpose value="Maintenance" destination="jms/XPDinteg_CtrlQ"/>

     </routing>

     <header-mapping>

          <param name="ibmxpdintegrator-messagepurpose" value="MessagePurpose" type="String"/>

          <param name="ibmxpdintegrator-resourcetype" value="ResourceType" type="String"/>

          <param name="ibmxpdintegrator-description" value="Description" type="String"/>

          <param name="ibmxpdintegrator-transporttype" value="TransportType" type="String"/>

          <param name="ibmxpdintegrator-transfermode" value="TransferMode" type="String"/>

          <param name="ibmxpdintegrator-encoding" value="Encoding" type="String"/>

          <param name="ibmxpdintegrator-destinationcreationMode" value="DestinationCreationMode" type="String"/>

          <param name="ibmxpdintegrator-destinationpath" value="DestinationPath" type="String"/>

          <param name="ibmxpdintegrator-destinationname" value="DestinationName" type="String"/>

          <param name="ibmxpdintegrator-locationid" value="LocationId" type="String"/>

          <param name="ibmxpdintegrator-messageSrcid" value="MessageSrcId" type="String"/>

          <param name="ibmxpdintegrator-transactionid" value="TransactionId" type="String"/>

          <param name="ibmxpdintegrator-messageid" value="MessageId" type="String"/>

          <param name="ibmxpdintegrator-messagepriority" value="MessagePriority" type="Integer"/>

          <param name="ibmxpdintegrator-sequenceno" value="SequenceNo" type="Integer"/>

          <param name="ibmxpdintegrator-resourcesize" value="ResourceSize" type="Long"/>

          <param name="ibmxpdintegrator-buildinterval" value="BuildInterval" type="Long"/>

          <param name="ibmxpdintegrator-endofdata" value="EndOfData" type="Boolean"/>

          <param name="ibmxpdintegrator-transferconfirmationmode" value="TransferConfirmationMode" type="String"/>

          <param name="ibmxpdintegrator-writeotherfilename" value="WriteOtherFileName" type="String"/>

          <param name="ibmxpdintegrator-resourcecmd" value="ResourceCmd" type="String"/>

          <param name="ibmxpdintegrator-ibmxpdintegrator-headerversion" value="HeaderVersion" type="String"/>

     </header-mapping>

</rest>

The following Table 24 explains the possible parameters for the REST adapter.

Table 24: REST adapter parameters

Property	Explanation
connectionFactory	JNDI key for the Microbroker. E.g.: jms/XPDinteg_ConnectionFactory need to map to the microbroker definition in the messaging section
routing.messagepurpose.<MessagePurpose>	JNDI key of the destination corresponding to the MessagePurpose. E.g.: FileTransfer requests are forwarded to the queue with the JNDI name "jms/XPDinteg_ReqInQ”
header-mapping.<HTTPheader>	This section contains the mapping between the HTTP header an the Expeditor integrator message headers E.g.: the HTTP header “ibmxpdintegrator-messagepurpose is mapped to the MessageHeader “MessagePurpose”

The Webcontainer can not be configured using the XPDinteg.xml. Parameters of interest are the HTTP and HTTPS port and the HTTP address setting.

Please find in Table 25 the detailed description about the Web Container parameters and its defaults.

Table 25: IBM Lotus Expeditor Client WebContainer parameters for Expeditor integrator

Property	Explanation
*HTTP* Port	Defines the port used by the HTTP Service listener to listen for requests. A value of 0 indicates that a port will be selected at random when the platform starts. A value of -1 indicates that no listener will be started to listen for HTTP requests. This property now supports a list of values. *Default:* *8777*
*HTTPS* Port	Defines the port used by the HTTPS Service listener to listen for requests. A value of 0 indicates that a port will be selected at random when the platform starts. A value of -1 indicates that no listener will be started to listen for HTTP requests. This property now supports a list of values. *Default:* *9001*
HTTP Address	Defines the host address for the default ports that the Web Container listens on. If this property is defined then the Web Container will only listen for requests that come through this IP address. The special value ALL indicates all available IP addresses on the computer will be used. The value of this property may be a resolved name or IP address (for example, www.ibm.com, 192.168.0.101, localhost). *Default:* *ALL*
UseLocalAddress	Defines if the Web container only listens on the localhost, default is true, must be set to false to allow remote access. Property name: com.ibm.pvc.webcontainer.useLocalAddress

To change these parameters after the Expeditor integrator was deployed, the following file steps need to be done:

find the file <XPDinteg_Home>\rcp\eclipse\plugins\com.ibm.rcp.base_<version>\config\pbuilder\rcpinstall.properties
Update the HTTP port parameter: -Dcom.ibm.pvc.webcontainer.port=yournewport
Update the HTTPS portparameter: -Dcom.ibm.pvc.webcontainer.port.secure=yournewport
Update the HTTP adress parameter: -Dcom.ibm.pvc.webcontainer.http.address=newadress
Update the UseLocalAddress parameter: -Dcom.ibm.pvc.webcontainer.useLocalAddress=false
Restart the Expeditor integrator.

The file retrieval and send file tasks can be achieved remotely by using the Expeditor integrator capabilities.

Please, refer to APPENDIX B – Technical Details for steps to enable the IBM Lotus Expeditor Client WebContainer access through SSL.

Graphical User Interface Access Configuration (Section_17)

IBM Lotus Expeditor integrator provides a framework for a browser-based graphical user interface. This JavaScript based framework provides common look and feel. It consists of the Expeditor integrator Start Page which displayes a status overview and additional pages which can be dynamically plugged in as user interfaces for custom applications.

Per default, it provides access to administrative functions, for example:

Administrators page for installation, un-installation, start / stop of components and of the complete runtime
Monitor page for displaying current and historical status information of ACS Flows and Adapters.
Configuration page for retrieving, editing and deploying the configuration of Expeditor integrator runtimes (e.g. helps to create the XPDinteg.xml config file)
Test page which can be used to run test cases on selected Expeditor integrator runtimes and MQ-based back-ends.

Per default, the GUI can be accessed under: http://xpdinteghost:8777/ui/home
(Please, refer to section ‎7 for more Expeditor integrator GUI details.)

General format:

<GUI>

     <web-app name="com.ibm.rcp.integrator.ui.admin">

          <enabled>TRUE</enabled>

          <displayed_for_role>

               <role>uiadmin</role>

          </displayed_for_role>

     </web-app>

     <web-app name="com.ibm.rcp.integrator.ui.config">

…

     </web-app>

…

</GUI>

Table 26 provides an explanation of the available properties.

Table 26: GUI configuration properties

Property	Explanation
<web-app name=	Property tag for the configuration section of one GUI page. name is the name of the installed plug-in (Servlet) which provides the GUI functions for this page. e.g. <web-app name=”com.ibm.rcp.integrator.ui.admin”
<enabled>	Enables / disables this application’s page in the common Expeditor integrator GUI. values: TRUE or FALSE
<displayed_for_role>	List of user access roles for which this application’s page is displayed. These roles must match the authenticated user’s roles in the Expeditor User Admin Service. Note: This setting does not prevent directly accessing the URI of this application. It just does not display this application in the common Expeditor integrator GUI.

The users and roles are managed by the User Admin Service which can also be configured by Expeditor integrator (see section ‎8). The default users and roles are loaded from the <XPDINTEG_HOME>/config/system/XPDintegDefaultRoles.xml file. Changes to these roles can either be applied by the Expeditor Client Manager (server) or through Expeditor integrator ConfigUpdate messages (see chapter ‎8.3 Updating the user Admin SErvice configuration with Expeditor integrator).

An example is provided in Listing 24.

Listing 24: Expeditor integrator GUI configuration example (integrates the default Admin and Config GUI pages)

<GUI>

     <web-app name="com.ibm.rcp.integrator.ui.admin">

          <enabled>TRUE</enabled>

          <displayed_for_role>

               <role>uiadmin</role>

          </displayed_for_role>

     </web-app>

     <web-app name="com.ibm.rcp.integrator.ui.config">

          <enabled>TRUE</enabled>

          <displayed_for_role>

               <role>uiconfig</role>

          </displayed_for_role>

     </web-app>

</GUI>

The Expeditor integrator GUI provides the Configuration Page. This can be used to create a custom XPDinteg.xml configuration file and to edit all the possible configuration options mentioned earlier.
Please, refer to Using the IBM Expeditor integrator platform (‎Ref_2) for more details about using the Expeditor integrator GUI.

Per default, only a locally running browser can access the Expeditor integrator GUI. If required, remote access from other computers can be enabled by adding the following lines:

/ui=*:[8777,8778]
/config=*:[8777,8778]
/admin=*:[8777,8778]
/monitor=*:[8777,8778]
/testtool=*:[8777,8778]
/welcome=*:[8777,8778]

in the vconfig.txt file under either

<XPDintegHome>/config/system/ssl/ or
<XPDintegHome>\rcp\eclipse\plugins\com.ibm.rcp.integrator.config.deployment-<date>\payload\config\system\ssl\\

(Changes according to a. require platform restart and will be ‘lost’ after platform reset. Changes according to b. need platform reset, but will ‘survive’ later reset.)

Expeditor integrator Resource Mapper Configuration (Section_8)

The Expeditor integrator Resource Mapper provides the opportunity to configure parameters which are required for transferring files and other resources from Expeditor integrator (outbound) and to Expeditor integrator (inbound) in a common place for a group of resources. Resource groups with common properties are classified through the ResourceType property. The ResourceType is an Expeditor integrator JMS Custom Header property through which different data messages can be identified (see Using the IBM Expeditor integrator platform ‎Ref_2 for more details).

Detailed configuration parameters which apply to a given Resource Type can be grouped in the Resource Mapper in order to make the Expeditor integrator configuration more readable. There are default Resource Types, but custom Resource Types can also be introduced to group resources and their configuration.

Inbound Resource Mapper (Transfer from Back-end to Expeditor integrator)

If the ResourceType property is used for incoming messages (inbound), the Resource Mapper can hold configuration values which are applied to the received resource (e.g. ResourceType=SampleFtpFile, then all resource properties could be stored in the Resource Mapper rather then providing them again and again in each incoming message with the same file as payload). This means that the Resource Mapper is used as configuration store for additional JMS Custom Header properties which are added to an incoming/triggering JMS message. Therefore, the Resource Mapper configuration properties are processed in the same way as the original JMS custom message header properties (e.g. they have higher priority than the ACS Activity configuration in the XPDinteg.xml and in the ACS flow definition files). The mapping key is the ResourceType.

General Format:

<resources>

     <inbound-mappings>

          <resource-mapping type="SampleFtpFile">

               <param name="TransportType" value="FTP"/>

               <param name="Description" value="Write SAMPLE.TXT sample FTP file to TMP directory"/>

               <param name="TransferMode" value="ASCII"/>

               <param name="DestinationCreationMode" value="APPEND"/>

               <param name="DestinationPath" value="/"/>

               <param name="DestinationName" value="SAMPLE.TXT"/>

               <param name=”FtpTempFileExtension” value =”TMP”/>

               <param name="Encoding" value="UTF-8"/>

               <param name="FtpServer" value="ftp_server_name"/>

               <param name="FtpServerPort" value="21"/>

               <param name="FtpPassive" value="TRUE"/>

               <param name="FtpUser" value="ftp_user"/>

               <param name="FtpPassword" value="ftp_passwd"/>

               <param name="FtpType" value="DEFAULT"/>

          </resource-mapping>

Basically, all <param name … /> properties which are available for the Expeditor integrator Resource Adapters can be used in the Resource Mapper configuration (refer to chapter ‎4.4 Resource Monitor and Resource Adapter Configuration for the Resource Adapter configuration options). Table 27 shows the configuration options for the Inbound Resource Mapper.

Table 27: Inbound Resource Mapper configuration options
(Please, refer to the Users Guide about the currently supported ResourceTypes and their possible configuration values (see Ref_2))

Property	Explanation
<resources> <*inbound*-mappings>	Resource Mapper direction: *inbound* for resource transmission back-end -> Expeditor integrator *outbound* for resource transmission Expeditor integrator -> back-end
<resource-mapping type=	"*SampleFtpFile*" Maps to JMS Custom Header property ResourceType (see Using the IBM Expeditor integrator platform;Ref_2). This unique ID is used to assign resource adapter settings to settings in the Resource Mapper
<param name="TransportType" value=	Different transport types that identify the Resource Adapter which is used. Possible values: "*FTP" – for FTP Adapter, "LocalFileSystem" – for Local File System Adapter, "SSH*" – for SSH File Adapter, "DB" – for Database Adapter
<param name="Description" value=	String: description of the resource mapping
<param name= "TransferMode" value="	"ASCII" or "BINARY" "ASCII" – (file) transfer mode is ASCII (e.g. for FTP access) "BINARY" – (file) transfer mode is binary (e.g. for FTP access)
<param name= "DestinationCreationMode" value=	Defines write operation in case the resource already exists. "APPEND" – append new (file) resource to existing one "OVERWRITE" – overwrite with new (file) resource
<param name= "DestinationPath" value=	String which contains target path to which the received resource transferred (e.g. file directory – forward slashes only) Note: Must not be empty (use value="/"/> instead)). And, the DEFAULT FtpType does require a leading “/” for navigating to the root path.
<param name= "DestinationName" value=	String which contains the name of the destination resource (e.g. file name). This value can be provided dynamically (e.g. *value="<TRANSID_8>.TXT" would create a file name out of the last 8 digits of the transaction ID with the file extension .TXT*, see Using the IBM Expeditor integrator platform for more options; ‎Ref_2).
<param name=”FtpTempFileExtension” value =	File extension of temporary file name in destination directory which is used during FTP transfer, e.g. set value to “XMP” for tempfile.XMP (default: “TMP”) (Note: Use parameter SshTempFileExtension for SSH and parameter LocalTempFileExtension for local file system file transfer.)
<param name=”SshTempFileExtension” value =	File extension of temporary file name in destination directory which is used during SSH transfer, e.g. set value to “XMP” for tempfile.XMP (default: “TMP”)
<param name=”LocalTempFileExtension” value =	File extension of temporary file name in destination directory which is used during LocalFileSystem transfer, e.g. set value to “XMP” for tempfile.XMP (default: “TMP”)
<param name="Encoding" value=	“UTF-8” or “UTF-16” etc. Type of data encoding.
<param name="FtpServer" value=	String with hostname or IP address of FTP target server in case of FTP file transfer
<param name= "FtpServerPort" value=	String with port number of FTP target server in case of FTP file transfer (default: value="21")
<param name="FtpPassive" value=	Indicates whether passive or active transfer mode is used for FTP file transfer. Possible values: "TRUE" or "FALSE"
<param name="FtpUser" value=	"ftp_user" – contains the name of the FTP target server user account
<param name="FtpPassword" value="ftp_passwd"/>	"ftp_passwd" – contains the password for the FTP target server user account above (This can also be provided as encrypted string. Use the PasswordUtil to encrypt password before including it in here, see chapter 4.12 Password encryption utility)
<param name="FtpType" value=	Defines the type of the FTP target server "*DEFAULT" – for standard OS FTP servers (Linux, Unix and Windows) "4690" – for FTP server on 4690 PoS controllers This setting must be provided so that the adapter can use the correct command for enlisting files of the target directory. (Make sure that the DestinationPath* is correctly provided, e.g. the 4690 type may understand the root path without a leading “/”, the DEFAULT server does require it.)
<param name="SshServer" value=	String with hostname or IP address of SSH target server in case of SSH based file transfer
<param name= "SshServerPort" value=	String with port number of SSH target server in case of SSH based file transfer (default: value="22")
<param name="SshUser" value=	"ssh_user" – contains the name of the SSH target server user account
<param name= "SshPassword" value=	"ssh_passwd" – contains the password for the SSH target server user account above (This can also be provided as encrypted string. Use the PasswordUtil to encrypt password before including it in here, see chapter 4.12 Password encryption utility)
<param name="SshType" value=	SSH server type: “SFTP” or “SCP”
<param name "4690TestPermissionFilename" value=	Name of the file to be created for determining the permission rights on the IBM 4690 POS controller. The file name value includes the path and can be provided dynamically (e.g. value="<TRANSID_8>.TXT" would create a file name out of the last 8 digits of the transaction ID with the file extension .TXT in <XPDINTEG_HOME>, see Using the IBM Expeditor integrator platform for more options; ‎Ref_2). More details are given in chapter 4.4.2. Note: The test file name must be unique for each adapter! Otherwise, race conditions will occur when additional adapters and flows try to write to the same target directory. The default file name is dynamically created based on the last 8 digits of the transaction id and the extension is .xpd. (produces the same file name like manually specifying <TRANSID_8>.xpd)

Configuration examples for Local File System Adapter Resource Mapping are given in section 3 (Listing 3) and in the included XPDinteg.xml file.

Outbound Resource Mapper (Transfer from Expeditor integrator to Back-end)

The ResourceType property can also be used during Resource Adapter configuration (see chapter ‎4.4 Resource Monitor and Resource adapter Configuration) to assign resource access configuration properties to a group of Adapters or a single Adapter and to outgoing data messages (outbound). For example, if the a FTP Resource Adapter is configured with

<configuration>

<param name="ResourceType" value="SampleFtpFile"/>

(ResourceType=SampleFtpFile), all further configuration values do not need to be placed in the Adapter’s <configuration> section. These configuration values could also be stored in the outbound Resource Mapper so that it is usable by other Adapters and Resources as well.

General Format:

<resources>

     <outbound-mappings>

          <resource-mapping type="SampleFtpFile">

               <param name="TransportType" value="FTP"/>

               <param name="Description" value="Sample FTP file"/>

               <param name="TransferMode" value="ASCII"/>

               <param name="TransferConfirmationMode" value="WriteOtherFile"/>

               <param name="WriteOtherFileName" value="sample.trf"/>

               <param name="Encoding" value="UTF-8"/>

               <param name="FtpServer" value="ftp_server_name"/>

               <param name="FtpServerPort" value="21"/>

               <param name="FtpPassive" value="TRUE"/>

               <param name="FtpUser" value="ftp_user"/>

               <param name="FtpPassword" value="ftp_passwd"/>

               <param name="FtpType" value="DEFAULT"/>

               <param name="TransferPriority" value="9"/>

Many configuration values for the Outbound Resource Mapper are the same as the ones for the Inbound Resource Mapper and are also available for the Resource Monitor Adapter configuration. Refer to Table 28 for an overview of the configuration options.

Table 28: Outbound Resource Mapper configuration options
Please, refer to the Users Guide about the currently supported ResourceTypes and their possible configuration values (see ‎Ref_2)

Property	Explanation
<resources> <*outbound*-mappings>	Resource Mapper direction: *outbound* for resource transmission Expeditor integrator -> back-end inbound for resource transmission back-end -> Expeditor integrator
<resource-mapping type=	"*SampleFtpFile*" Maps to JMS Custom Header property ResourceType (see Using the IBM Expeditor integrator platform; ‎Ref_2). This unique ID is used to assign resource adapter settings to settings in the Resource Mapper.
<param name="TransportType" value=	Different transport types that identify the Resource Adapter which is used. Possible values: "*FTP" – for FTP Adapter, "LocalFileSystem" – for Local File System Adapter, "SSH*" – for SSH File Adapter, "DB" – for Database Adapter
<param name="Description" value=	String: description of the resource mapping
<param name= "TransferMode" value="	"ASCII" or "BINARY" "ASCII" – (file) transfer mode is ASCII (e.g. for FTP access) "BINARY" – (file) transfer mode is binary (e.g. for FTP access)
<param name= "TransferConfirmationMode" value=	“DELETE” or “RecreateZero” or “WriteOtherFile” Defines the action on the picked up file resource after successful transfer to the back-end queue. "*NONE" – leave the picked up file as it is (Note: With NONE, the file will trigger another transaction during the next polling interval!) "DELETE" – delete the file resource(s) in the source directory "RecreateZero" – recreate a file with length zero byte, but with the same name as the source file resource "WriteOtherFile*" – source file is re-named with the name provided in WriteOtherFileName
<param name= "WriteOtherFileName" value=	"*sample.trf*" String value with the file name in which the original transferred file should be re-named (if TransferConfirmationMode=WriteOtherFile)
<param name="Encoding" value=	“UTF-8” or “UTF-16” etc. Type of data encoding.
<param name="FtpServer" value=	String with hostname or IP address of FTP target server in case of FTP file transfer
<param name= "FtpServerPort" value=	String with port number of FTP target server in case of FTP file transfer (default: value="21")
<param name="FtpPassive" value=	Indicates whether passive or active transfer mode is used for FTP file transfer. Possible values: "TRUE" or "FALSE"
<param name="FtpUser" value=	"ftp_user" – contains the name of the FTP target server user account
<param name="FtpPassword" value="ftp_passwd"/>	"ftp_passwd" – contains the password for the FTP target server user account above (This can also be provided as encrypted string. Use the PasswordUtil to encrypt password before including it in here, see chapter Password encryption utility)
<param name="FtpType" value=	Defines the type of the FTP target server "*DEFAULT" – for standard OS FTP servers (Linux, Unix and Windows) "4690*" – for FTP server on 4690 PoS controllers
<param name="SshServer" value=	String with hostname or IP address of SSH target server in case of SSH based file transfer
<param name= "SshServerPort" value=	String with port number of SSH target server in case of SSH based file transfer (default: value="22")
<param name="SshUser" value=	"ssh_user" – contains the name of the SSH target server user account
<param name= "SshPassword" value=	"ssh_passwd" – contains the password for the SSH target server user account above (This can also be provided as encrypted string. Use the PasswordUtil to encrypt password before including it in here, see chapter Password encryption utility)
<param name="SshType" value=	SSH server type: “SFTP” or “SCP”
<param name "4690TestPermissionFilename" value=	Name of the file to be created for determining the permission rights on the IBM 4690 POS controller. The file name value includes the path and can be provided dynamically (e.g. value="<TRANSID_8>.TXT" would create a file name out of the last 8 digits of the transaction ID with the file extension .TXT in <XPDINTEG_HOME>, Name of the file to be created for determining the permission rights on the IBM 4690 POS controller. This value can be provided dynamically (e.g. value="<TRANSID_8>.TXT" would create a file name out of the last 8 digits of the transaction ID with the file extension .TXT, see Using the IBM Expeditor integrator platform for more options; ‎Ref_2). This parameter can be also set for the following activities in the ACS section: XPDINTEG_FILE_TRANSFER_CONFIRMATION; XPDINTEG_FILE_WRITE_TO_FTP. More details are given in chapter FTP Resource Adapter. Note: The test file name must be unique for each adapter! Otherwise, race conditions will occur when additional adapters and flows try to write to the same target directory. The default file name is dynamically created based on the last 8 digits of the transaction id and the extension is .xpd. (produces the same file name like manually specifying <TRANSID_8>.xpd)

Configuration examples for Local File System Adapter Resource Mapping are given in section 3 (Listing 2) and in the included XPDinteg.xml file.

Default Resource Mapper Configurations

Standard Expeditor integrator Resource Mappers

The following Listing 25 shows the standard Resource Mappers which are required for Expeditor integrators operation.

Listing 25: Standard Expeditor integrator Resource Mapper configuration (for ConfigUpdate and ScriptFile control messages)

<inbound-mappings>

     <<resource-mapping type="ConfigurationUpdateFile">

          <param name="TransportType" value="LocalFileSystem"/>

          <param name="Description" value="Properties File"/>

          <param name="TransferMode" value="ASCII"/>

          <param name="DestinationCreationMode" value="OVERWRITE"/>

          <param name="DestinationPath" value="config"/>

          <param name="DestinationName" value="XPDinteg.xml"/>

          <param name="Encoding" value="UTF-8"/>

     </resource-mapping>

     <resource-mapping type="ScriptFile">

          <param name="TransportType" value="LocalFileSystem"/>

          <param name="Description" value="Script File"/>

          <param name="TransferMode" value="ASCII"/>

          <param name="DestinationCreationMode" value="OVERWRITE"/>

          <param name="DestinationPath" value="config"/>

          <param name="DestinationName" value="script.bat"/>

          <param name="Encoding" value="UTF-8"/>

     </resource-mapping>

</inbound-mappings>

Example Resource Mappers for Retail Customers

Example file transfer configurations for the Resource Mapper are given in sample files in the <XPDINTEG_HOME>/samples/config directory (also, see chapter ‎3.2.2 Configuring Local File System Resource Adapters).
Mappings for the following file types are provided:

Inbound
- PriceUpdFile
- MappingDataFile
- DiscountDataFile
- ScaleDataFile
- PrintLabelFile
- ShelfLabelFile
Outbound
- PosTransDataFile1
- PosTransDataFile2
- OtherTransDataFile
- PosProdDataFile
- TlogFile
- CreditNotesFile
- PaybackDataFile
- PressDataFile
- EventsFile

An example configuration file XPDinteg.xml can also be found in the <XPDINTEG_HOME>/samples/config folder.

Application Control Service Configuration (Section_9)

Configuration of Application Use Cases (Expeditor integrator Service Flows)

Since the Expeditor integrator is purely messaging and event driven, the behavior can be configured from the use case perspective by configuring the Expeditor integrator Application Control Service (ACS) flows. Expeditor integrator system flows are stored in <XPDINTEG_HOME>\flowdefs\system and should not be changed otherwise the correct operation can not be guaranteed. Expeditor integrator default flow definition files are located in the <XPDINTEG_HOME>/flowdefs/default folder (e.g. for file transmission, database record updates). Custom developed flows should be placed into the Expeditor integrator flow root folder <XPDINTEG_HOME>/flowdefs (configurable in Section_9 of the XPDinteg.xml). Example ACS Flow definition files can be found under <XPDINTEG_HOME>/samples/flowdefs folder.

Each ACS flow consists of a sequence of Activities that perform defined tasks (see Figure 11). Each flow is started by a configurable OSGi Event Admin trigger event. The Expeditor integrator is delivered with a default set of Activities that can be re-configured and newly chained together to fulfill new business use cases.

REST Adapter resource monitoring

Figure 11: Expeditor integrator Resource Adapters monitor resources and notify the Resource Monitor Service in case of changes. Then, the Resource Monitor Service and the Dispatcher Service publish defined flow trigger events using the OSGi Event Admin Service to which ACS Flows have subscribed to. If the flow trigger event matches a given flow, the flow is executed.

Please, refer for further details to the Using the IBM Expeditor integrator platform (‎Ref_2).

General ACS Configuration

The Expeditor integrator Application Control Service also provides configuration options in Section_9 the XPDinteg.xml file.

General format:

<application-control-service>

     <definition-settings>

          <directory>directory_for_flowdef_files</directory>

          <poll-interval>flow_def_directory_polling_intervall_in_msec</poll-interval>

          <extension>flow_config_files_extension </extension>

          <retryInterval>read_retry_intervall_in_msec</retryInterval>

     </definition-settings>

     <permissions>

          <multiple-flows-per-topic>false</multiple-flows-per-topic>

     </permissions>

Table 29: Application Control Service configuration

Property	Explanation
<application-control-service> <definition-settings>	Tag indicating the ACS configuration section
<directory>	directory_for_flowdef_files String which contains the local directory in which the ACS flow definition files are stored (default: <XPDINTEG_HOME>/*flowdefs*)
<poll-interval>	flow_def_directory_polling_intervall_in_msec polling interval for the flow definition file changes in msec (default: 60’000ms = 1min)
<extension>	flow_config_files_extension standard file extension which indicates a flow definition file (default = .flow)
<retryInterval>	*read_retry_intervall_in_msec* retry interval in msec after which reading of updated ACS flow files is tried (in case it failed before)
<permissions> <multiple-flows-per-topic> </multiple-flows-per-topic>	*true* OR *false* defines whether one trigger event could kick-off more then one flow (default = false; recommended). One trigger event could start multiple flows. This becomes complex quickly and is therefore only recommended for experienced users.

An example is given in Listing 26.

Listing 26: General ACS configuration example

<application-control-service>

     <definition-settings>

          <directory>flowdefs</directory>

          <poll-interval>120000</poll-interval>

          <extension>flow</extension>

          <retryInterval>30000</retryInterval>

     </definition-settings>

     <permissions>

          <multiple-flows-per-topic>false</multiple-flows-per-topic>

     </permissions>

ACS Activity Configuration

The Using the IBM Expeditor integrator platform contains the list of all available Expeditor integrator Application Control Service Activities (see ‎Ref_2). Some Activities can be independently configured in the flow definition. This allows for different handling of resources for different messages and flows.
The following configuration priority is defined for cases where the JMS Custom Header property, the ACS Activity configuration and the configuration in Section_9 of the XPDinteg.xml are provided:

The JMS Custom Header properties and the optionally assigned properties in the Resource Mapper configuration have always highest priority. They overwrite the XPDinteg.xml and the ACS Activity/Flow settings.
If JMS Custom Header property is not set, the definitions in the ACS Activity/Flow settings are taken.
Lowest priority has the configuration stored in XPDinteg.xml. These settings are always overruled by the JMS Custom Header properties and the ACS Activity/Flow settings.

Table 29 shows a selection of possible configuration options for the most important Activities. Basically, message related Activities can re-use the JMS Message Header properties. The File/SSH/LocalFileSystem related Activities can also re-use the <param … value=…/> properties of the Resource Adapters.

Listing 26 shows the default configuration of Expeditor integrator for these ACS Activities which can be adjusted to customer specific needs.

Table 30: ACS Activity configuration

Property	Explanation
<application-control-service> < activity-configurations >	Tag indicating the ACS Activity configuration section
<configuration activity= "XPDINTEG_BROWSE_FTP_DIRECTORY">	Name of the Expeditor integrator activity (see Activity catalogue in Using the IBM Expeditor integrator platform)
<param name= "resource_adapter_property" value="my_value"/>	List of <param name … value=..> pairs which contain configuration options for each activity (see params in Resource Adapter configuration. If these parameters are provided in JMS Custom Header and Resource Mapper properties of an involved message, then the message’s properties have higher priority and will be used. If these parameters are not set here, configuration values from the XPDinteg.xml file will be taken instead.
<param name="*FtpXxx*" value=	FTP Resource Adapter specific configuration values (see chapter 4.4 Resource Monitor and Resource Adapter Configuration) For Activities: XPDINTEG_BROWSE_FTP_DIRECTORY, XPDINTEG_FILE_READ_FTP, XPDINTEG_FILE_WRITE_TO_FTP XPDINTEG_FILE_TRANSFER_CONFIRMATION
<param name="SshXxx" value=	SSH Resource Adapter specific configuration values (see chapter 4.4 Resource Monitor and Resource Adapter Configuration) For Activities: XPDINTEG_BROWSE_SSH_DIRECTORY, XPDINTEG_FILE_READ_SSH, XPDINTEG_FILE_WRITE_TO_SSH XPDINTEG_FILE_TRANSFER_CONFIRMATION
<param name= "*RetryAttempts" value="200"/> <param name="RetryInterval*" value="5000"/>	RetryAttempts – no. of retry cycles in case the remote server is temporary not available RetryInterval – time interval after which the Adapter is polled again For Activities: XPDINTEG_FILE_WRITE_TO_FILE_SYSTEM, XPDINTEG_FILE_WRITE_TO_FTP, XPDINTEG_FILE_WRITE_TO_SSH, XPDINTEG_FILE_TRANSFER_CONFIRMATION
<param name="CreateHeaderVersion" value="2.0"/> <param name="MessageSegmentSize" value="2000"/>	<param name="CreateHeaderVersion" tells the message creating Activity in which Expeditor integrator *header version* it should be build. <param name="MessageSegmentSize“ defines the maximum size of the created messages in KByte. If larger data chunks must be transferred, e.g. large files, this is the threshold value for the size of the created message segements which contain the large data object. For Activities: XPDINTEG_MESSAGE_WRITE, XPDINTEG_FILE_TO_MESSAGE_WRITE
<param name= "InvalidMessageFailureAction" value=	"DISCARD" or "REMOVE" Configuration for cases where any setting in the involved JMS message is wrong (wrong header or payload) InvalidMessageFailureAction value= "DISCARD" – deletes wrong message "REMOVE" – moves wrong message to queue configured under <param name= "RemoveTargetJNDI" value=... For Activities: XPDINTEG_MESSAGE_TO_FILE, XPDINTEG_MESSAGE_READ
<param name= "RollbackMessageAction" value="	"DISCARD" or "REMOVE" or "PUT_BACK" "DISCARD" – deletes wrong message "REMOVE" – moves wrong message to queue configured under <param name= "RemoveTargetJNDI" value=... "PUT_BACK" – puts message which can not be processed to original InQ (no of retries was exceeded); Note: This could cause infinite looping of un-processable messages. For Activities: all
<param name= "RemoveTargetJNDI" value=	e.g. "jms/XPDinteg_ServerDeadletterQ" JNDI name of the destination queue regarding to value= "REMOVE" of InvalidMessageFailureAction or RollbackMessageAction
<param name= "script-execution" value=	"true" OR "false" – configures whether Script execution is allowed or not. For Activity: XPDINTEG_FILE_EXECUTE
<param name= "HouseKeeping_specific_params" value=	For Activity: HOUSE_KEEPING_SYSTEM_RESOURCES_ACTIVITY
<param name= "ISACollector_specific_params" value=	For Activity: XPDINTEG_ISA_COLLECTOR_ADDFILES_ACTIVITY

Listing 27: Application Control Activity Confguration

<application-control-service>

     <activity-configurations>

          <configuration activity="XPDINTEG_BROWSE_FTP_DIRECTORY">

               <param name="ftp_related_parameters!"/>

          </configuration>

          <configuration activity="XPDINTEG_BROWSE_SSH_DIRECTORY">

               <param name="ssh_related_parameters!“/>

          </configuration>

          <configuration activity="XPDINTEG_FILE_READ_FTP">

               <param name="ftp_related_parameters!"/>

          </configuration>

          <configuration activity="XPDINTEG_FILE_READ_SSH">

               <param name="ssh_related_parameters!“/>

          </configuration>

          <configuration activity="XPDINTEG_FILE_WRITE_TO_FILE_SYSTEM">

               <param name="RetryAttempts" value="200"/>

               <param name="RetryInterval" value="5000"/>

          </configuration>

          <configuration activity="XPDINTEG_FILE_WRITE_TO_FTP">

               <param name="ftp_resource_adapter_related_params“ .../>

          </configuration>

          <configuration activity="XPDINTEG_FILE_WRITE_TO_SSH">

               <param name="ssj_resource_adapter_related_params“ .../>

          </configuration>

          <configuration activity="XPDINTEG_MESSAGE_TO_FILE">

               <param name="Encoding" value="UTF-8"/>

               <param name="InvalidMessageFailureAction" value="DISCARD"/>

               <param name="RollbackMessageAction" value="PUT_BACK"/>

               <param name="RemoveTargetJNDI" value="jms/XPDinteg_ServerDeadletterQ"/>

          </configuration>

          <configuration activity="XPDINTEG_MESSAGE_READ">

               <param name="InvalidMessageFailureAction" value="DISCARD"/>

               <param name="RollbackMessageAction" value="PUT_BACK"/>

               <param name="RemoveTargetJNDI" value="jms/XPDinteg_ServerDeadletterQ"/>

          </configuration>

          <configuration activity="XPDINTEG_FILE_TO_MESSAGE_WRITE">

               <param name="MessageSegmentSize" value="2000"/>

               <param name="Encoding" value="UTF-8"/>

               <param name="CreateHeaderVersion" value="2.0"/>

          </configuration>

          <configuration activity="XPDINTEG_MESSAGE_WRITE">

               <param name="CreateHeaderVersion" value="2.0"/>

          </configuration>

          <configuration activity="XPDINTEG_VALIDATE_TRANSFORM_ACTIVITY">

               <param name="XSDLocation" value="config\system\XPDinteg.xsd"/>

               <param name="XSLTLocation" value="config\system\XPDinteg.xsl"/>

               <param name="OutputXMLLocation" value="config\system\XPDintegConfig.xml"/>

          </configuration>

          <configuration activity="XPDINTEG_FILE_EXECUTE">

               <param name="script-execution" value="true"/>

          </configuration>

          <configuration activity="XPDINTEG_FILE_TRANSFER_CONFIRMATION">

               <param name="FtpServer" value="localhost"/>

               <param name="FtpServerPort" value="21"/>

               <param name="FtpPassive" value="TRUE"/>

               <param name="FtpUser" value="test"/>

               <param name="FtpPassword" value="test"/>

               <param name="FtpType" value="4690"/>

               <param name="SshServer" value="ssh_server_name"/>

               <param name="SshServerPort" value="22"/>

               <param name="SshUser" value="ssh_user"/>

               <param name="SshPassword" value="ssh_passwd"/>

               <param name="SshType" value="SFTP"/>

               <param name="RetryAttempts" value="200"/>

               <param name="RetryInterval" value="5000"/>

          </configuration>

          <!-- House Keeping Configuration / more details see in House Keeping flow chapter ‎6.7 House Keeping Flow -->

          <configuration activity="HOUSE_KEEPING_SYSTEM_RESOURCES_ACTIVITY">

               <param name="RAM" value="Threshold:256000;Action:REPORT_WARNING"/>

               <param name="DiskSpace" value="Threshold:1000000;Action:REPORT_WARNING"/>

               <param name="Files" value="Threshold:1000;Action:REPORT_WARNING"/>

          </configuration>

          <configuration activity="XPDINTEG_ISA_COLLECTOR_ADDFILES_ACTIVITY">

               <param name="FileList1" value="config/XPDinteg.xml"/>

               <param name="FileList2" value="config/system/XPDintegConfig.xml"/>

               <param name="FileList3" value="config/system/XPDinteg.xsd"/>

               <param name="FileList4" value="config/system/XPDinteg.xsl"/>

               <param name="IncludeOutput" value="true"/>

               <param name="OutputFileThreashold" value="1000"/>

               <param name="TransportType" value="BINARY"/>

               <param name="Encoding" value="UTF-8"/>

               <param name="TransferPriority" value="5"/>

          </configuration>

     </activity-configurations>

</application-control-service>

Custom Log Service configuration (Section_11)

The Custom Event Service allows forwarding of Log Events to the business backbone. Therefore, it gathers events from certain internal topics and puts them onto a queue that automatically forwards them to the business backbone. Therefore the log level, the monitored bundles, the topic list and log queue name need to be configured. Furthermore the Custom Log Service supports the Maintenance Mode. In this mode it stops forwarding events to the configured log queue.

Note: Be careful with using the Custom Log Service, because a detailed logging operation can have strong performance and network usage impact!

The Custom Log Service can be configured as follows (in Section_11 of the XPDinteg.xml).

General format:

<custom-log-service>

     <maintenance mode="OFF">

          <param name="LogToFile" value="FALSE"/>

          <param name="LogFileLocation" value="c://tmp//maintenance.log"/>

     </maintenance>

     <!-- DEBUG, INFO, WARNING, ERROR -->

     <threshold>ERROR</threshold>

     <monitored-bundles>

          <bundle>com.ibm.rcp.integrator.messagetofilemapper</bundle>

     </monitored-bundles>

     <!-- Monitored statuses: INSTALLED, STARTED, STOPPED -->

     <monitored-status>

          <status>INSTALLED</status>

     </monitored-status>

     <!-- Events sent to the following topics are captured. -->

     <filter-topics>

          <topic>com/ibm/integrator/businessevent/*</topic>

     </filter-topics>

     <message>

          <microbroker-jndi-key>jms/XPDinteg_ConnectionFactory</microbroker-jndi-key>

     </message>

Table 31 describes in detail the available Custom Log Service configuration parameters.

Table 31: Custom Log Service configuration properties

Property	Explanation
<*custom-log-service*>	Tag which identifies the Custom Log Service configuration section in the XPDinteg.xml file.
<maintenance mode=	"ON" or "OFF" indicates Maintenance Mode on or off (see chapter 6.6 Maintenance Mode)
<param name= "LogToFile" value=	"TRUE" or "FALSE" defines whether captured events during Maintenance Mode should be locally persisted to log file (specified unter LogFileLocation)
param name= "LogFileLocation" value=	String which contains the path and the name of the log file to which the received events are persisted during Maintenance Mode (if LogToFile=TRUE (e.g. "c://tmmaintenance.log")
<threshold>	Log Level, determines how much log information is written possible values: {DEBUG \| INFO \| WARNING \| ERROR}
<monitored-bundles>	Contains a list of bundle names (separated by the <bundle> tag) of which log events are monitored. When these bundles in this list reach the states specified under <monitored-status>, the Custom Log Service needs to forward this information to the LogQ of the Monitoring System.
<bundle>	String which contains the name of the monitored bundle. A single <bundle> tag contains one monitored bundle.
<monitored-status>	Contains a list of the monitored statuses, separated by the <status> tag.
<status>	A single <status> tag contains one monitored status- Possible values: INSTALLED - The bundle has been installed STARTED - The bundle has been started RESOLVED - The bundle has been stopped When the bundles in the above list reach these specific states, the Custom Log Service needs to send this information to the LogQ of the Monitoring System.
<filter-topics>	Contains a list of OSGi Event Admin Service event topics (separated by the <topic> tag) which the Custom Log Service is subscribed to. The Custom Log service will forward these events to the configured LogQ.
<topic>	A single <topic> tag contains one topic. Wildcards are allowed for the business event topics. Details are provided further below.
<message.microbroker-jndi-key>	micro broker JNDI Key used to connect to local micro broker for sending the log events to the local LogQ
<message.microbroker-logq-key>	Local Queue JNDI key to forward the log events. This queue needs to be bridged to a business backbone queue (e.g. LogQ; refer to the <messaging-service> section in the XPDinteg.xml file for its configuration).

The values for the <topic> tag are flexible because wildcards are supported. The following topic naming rules apply to Expeditor integrator's <topic> configuration:
Basic structure:

com/ibm/integrator/XPDintegApplStatusEvent/
ACS Flow execution status events:
- com/ibm/integrator/FlowStatus/<flowname>/ {STARTED | FINISHED | FAILED}
ACS Activity execution status events:
- com/ibm/integrator/FlowStatus/<flowname>/<activityname>/ {INITIALIZED | EXECUTING | EXECUTED}

· ACS Flow transaction status events (=Business Event for monitoring of transactional state of ACS flow):
com/ibm/integrator/businessevent/<flowname>/<state>

<flowname> describes the name of the monitored flow.
The flow name is taken from the <name> parameter of the <process> tag in the flow definition file.
<state> describes the state of the ACS flow process transaction.
Possible values:
- TRANSACTION_STARTED
- TRANSACTION_FAILED (failure scenario)
- TRANSACTION_COMPLETED (success scenario)
- TRANSACTION_PROCESSING

The wildcard “*” can only be used at the end of a topic.

Listing 28 shows an example configuration for the Custom Log Service.

Listing 28: Custom Log Service sample configuration

<custom-log-service>

     <maintenance mode="OFF">

          <param name="LogToFile" value="TRUE" | "FALSE"/>

          <param name="LogFileLocation" value="c://tmp//maintenance.log"/>

     </maintenance>

     <threshold>ERROR</threshold>

     <monitored-bundles>

          <bundle>com.ibm.rcp.integrator.messagetofilemapper</bundle>

          <bundle>com.ibm.rcp.integrator.transactionfilemapper</bundle>

     </monitored-bundles>

     <monitored-status>

          <status>INSTALLED</status>

     </monitored-status>

     <filter-topics>

          <topic>com/ibm/integrator/XPDintegApplStatusEvent</topic>

          <topic>com/ibm/integrator/businessevent/*</topic>

          <topic>com/ibm/integrator/flowname</topic>

     </filter-topics>

     <message>

          <microbroker-jndi-key>jms/XPDinteg_ConnectionFactory</microbroker-jndi-key>

          <microbroker-logq-key>jms/XPDinteg_logQueue</microbroker-logq-key>

     </message>

</custom-log-service>

Custom Event Service configuration (Section_12)

The Custom Event Service allows forwarding of Business Events to the business (messaging) back-end. It gathers events from internal event with filtered event topics and puts them into the local event queue which automatically forwards these events to the Event Queue of the business back-end. Event topic filters can be configured to define the events which need to be forwarded.
The Custom Event Service also supports the Expeditor integrator Maintenance Mode during which event forwarding is stopped to avoid flooding the business back-end with events due to a planned maintenance outage (see chapter ‎6.6 Maintenance Mode).

Note: Be careful with using the Custom Event Service, because a detailed event logging operation can have strong performance impact!

The Custom Event Service can be configured as follows (in Section_12 of the XPDinteg.xml).

General format:

<custom-event-service maintenance-mode="OFF">

     <maintenance mode="OFF">

          <param name="LogToFile" value="FALSE"/>

          <param name="LogFileLocation" value="c://tmp//maintenance.log"/>

     </maintenance>

     <filter-topics>

          <topic>com/ibm/integrator/businessevent/*</topic>

     </filter-topics>

     <message>

          <microbroker-jndi-key>jms/XPDinteg_ConnectionFactory</microbroker-jndi-key>

          <microbroker-eventq-key>jms/XPDinteg_EventQ</microbroker-eventq-key>

     </message>

</custom-event-service>

Table 32 describes in detail the configuration parameters.

Table 32: Custom Event Service configuration properties

Property	Explanation
<*custom-event-service*>	Tag which identifies the Custom Event Service configuration section in the XPDinteg.xml file.
<maintenance mode=	"ON" or "OFF" indicates Maintenance Mode on or off (see chapter 6.6 Maintenance Mode)
<param name= "LogToFile" value=	"TRUE" or "FALSE" defines whether captured events during Maintenance Mode should be locally persisted to log file (specified unter LogFileLocation)
param name= "LogFileLocation" value=}}}	String which contains the path and the name of the log file to which the received events are persisted during Maintenance Mode (if LogToFile=TRUE (e.g. "c:tmmaintenance.log")
<filter-topics>	Contains a list of OSGi Event Admin Service event topics (separated by the <topic> tag) which the Custom Event Service is subscribed to. The Custom Event Service will forward these events to the configured EventQ.
<topic>	A single <topic> tag contains one topic. Wildcards are allowed for the business event topics. Details are provided further below.
<microBroker-jndi-key>	micro broker JNDI Key used to connect to local micro broker for sending the business events to the local EventQ.
<microbroker-eventq-key>	Local Event Queue JNDI key to forward the business events. This queue needs to be bridged to an event queue of the messaging back-end (e.g. EventQ; refer to the <messaging-service> section in the XPDinteg.xml file for its configuration).

The values for the <topic> tag are flexible because wildcards are supported. The following topic naming rules apply to the <topic> configuration:

Basic flow transaction status event <topic> structure: com/ibm/integrator/businessevent/<flowname>/<state>
<flowname> describes the name of the monitored flow.
The flow name is taken from the name parameter of the <process> tag in the flow definition file.
<state> describes the state of the process transaction
Possible values:
- TRANSACTION_STARTED
- TRANSACTION_FAILED (failure scenario)
- TRANSACTION_COMPLETED (success scenario)
- TRANSACTION_PROCESSING

Note: The wildcard “*” can only be used at the end of a topic.

Listing 29 shows an example which configures the Custom Event Service to forward all com/ibm/integrator/businessevent/TRANSACTION_STARTED/FAILED/COMPLETED/PROCESSING events to the back-end queue configured under jms/XPDinteg_eventQueue.

Listing 29: Custom Event Service configuration example

<custom-event-service>

     <maintenance mode="OFF">

          <param name="LogToFile" value="TRUE" | "FALSE"/>

          <param name="LogFileLocation" value="c://tmp//maintenance.log"/>

     </maintenance>

     <filter-topics>

          <topic>com/ibm/integrator/businessevent/*</topic>

     </filter-topics>

     <message>

          <microbroker-jndi-key>jms/XPDinteg_ConnectionFactory</microbroker-jndi-key>

          <microbroker-eventq-key>jms/XPDinteg_EventQ</microbroker-eventq-key>

     </message>

</custom-event-service>

Example:
The Custom Event Service should catch all FAILED events from the PutFtpFiles ACS flow. Listing 30 shows the PutFtpFile.flow definition file with
<Process Name=”PutFtpFile_Process” …

Listing 30: Default_PutFtpFiles.flow

<?xml version="1.0" encoding="UTF-8"?>

     <Process Name="PutFtpFile_Process" Trigger="com/ibm/integrator/flowtriggerevent/FileTransfer/FTP/FtpFile/dispatcher">

          <XPDintegActivity

               Name="PutFtpFile_MessageToFile_FtpFile"

               ActivityName="XPDINTEG_MESSAGE_TO_FILE"

               JndiConnectionFactoryKey="jms/XPDinteg_ConnectionFactory"/>

          <XPDintegActivity

               Name="PutFtpFile_FileWriteToFTP_FtpFile"

               ActivityName="XPDINTEG_FILE_WRITE_TO_FTP"

               AdapterName="XPDINTEG_FTP_ADAPTER" />

     </Process>

If this flow fails, the following TRANSACTION_FAILED event will be published to the OSGi Event Admin Service:
<topic>com/ibm/integrator/businessevent/PutFtpFile_Process/FAILED</topic>

In order to capture this event type and forward it to the configured Event Queue of the back-end messaging system, the Custom Event Service configuration must contain this <topic> in its <filter-topics> list:
<topic>com/ibm/integrator/businessevent/PutFtpFile_Process/FAILED</topic>

If all other transaction statuses should also be captured, the following wildcard option would be sufficient as <filter-topics> in the Custom Event Service configuration:
topic>com/ibm/integrator/businessevent/PutFtpFile_Process/*</topic>

Expeditor integrator Tivoli Monitoring Service Configuration - TECLCF utility

If the Expeditor integrator uses the Expeditor integrator Tivoli Monitoring Service (iTMS) for sending events to the Tivoli Enterprise Console (TEC), additional configuration steps are required. This chapter explains the TecLcfUtil utility that was developed to support the administrator during the installation and configuration phases.

iTMS Configuration Options (Section_13)

Table 33 provides the currently available configuration options for the Expeditor integrator Tivoli Monitoring Service (iTMS). Make sure that these values are available and have been confirmed with TEC Administrator(s).

Table 33: Tivoli Monitoring Service (ITMS) configuration properties

Property	Explanation
<monitoring> <tec-monitor name="tec1"	Tag which identifies configuration for connecting to Tivoli back-end system TEC1
<maintenance mode=	"ON" or "OFF" indicates Maintenance Mode (see chapter 6.6 Maintenance Mode)
<param name= "LogToFile" value=	"TRUE" or "FALSE" defines whether captured events during Maintenance Mode should be locally persisted to log file (specified unter LogFileLocation)
param name= "LogFileLocation" value=}}}	String which contains the path and the name of the log file to which the received events are persisted during Maintenance Mode (if LogToFile=TRUE (e.g. "c:tmmaintenance.log")
<transport-type>	Disables or enables sending TEC events. Possible values: DISABLE – do not forward any TEC events LCF – forward events to local Tivoli endpoint SOCKET – forward events directly to TEC
<hostname> <port>	*tec-server-name.yourco.com* Hostname or IP address and port of Tivoli back-end system (TEC), required for transport type = SOCKET Default TEC port: 5529
<event-max-size>	Max size of the forwarded events in kByte (default: 4kByte)
<buffer-event-path>	path to the buffer for the TEC events (default: persistent/tec_name/tivoli.send.cache; tec_name is the name of the configured TEC connection)
<space-replacement>	Switch space replacement in events on or off: true OR false (default: true)
<trace> <filename> <level>	location of the trace file (default: persistent/tec_name/eif.trc ; tec_name is the name of the configured TEC connection) trace level is switched ON or OFF (default level: OFF)
<log> <filename> <level>	location of the log file (default: persistent/tec_name/eif.log ; tec_name is the name of the configured TEC connection) log level is switched ON or OFF (default level: OFF)
<threshold>	which logging events should be forwarded: ERROR \| WARNING \| DEBUG \| INFO
<topics> <topic>	Expditor integrator events with these topics are forwarded. Example: <topic>*com/ibm/integrator/XPDintegApplStatusEvent*</topic> Note: Leave <topics></topics> empty if no status events should be forwarded.
<monitored-bundles> <bundle>	List of Expeditor integrator components (bundle names) from which events are captured. Example: <bundle>*com.ibm.rcp.integrator.persistencesvc*</bundle> Note: Leave <monitored-bundles></monitored-bundles> empty if bundles should not be monitored.
<monitored-status> <status>	Status information of the monitored bundles which are forwarded as events to Tivoli back-end system (TEC) Possible values: INSTALLED, STARTED, STOPPED

Listing 31 contains an example for the iTMS configuration in which the locally installed Tivoli Endpoint is used as the communication channel between the remote server (system where Expeditor integrator is running on) and the Tivoli Monitoring back-end (TEC). This is especially recommended for customers with already installed Tivoli Endpoints since no additional port in the firewall between back-end and remote location needs to be opened.

Listing 31: Tivoli Monitoring Service configuration example for Expeditor integrator (connection to TEC1 is done through a locally installed Tivoli Endpoint)

<monitoring>

     <tec-monitor name="tec1">

          <maintenance mode="OFF">

               <param name="LogToFile" value="FALSE"/>

               <param name="LogFileLocation" value="c://tmp//maintenance.log"/>

          </maintenance>

          <transport-type>LCF</transport-type>

          <hostname>tec-server-name.yourco.com</hostname>

          <event-max-size>4</event-max-size>

          <buffer-event-path>persistent/tec1/tivoli.send.cache</buffer-event-path>

          <space-replacement>true</space-replacement>

          <trace>

               <filename>persistent/tec1/eif.trc</filename>

               <level>OFF</level>

          </trace>

          <log>

               <filename>persistent/tec1/eif.log</filename>

               <level>OFF</level>

          </log>

          <threshold>ERROR</threshold>

          <topics>

               <topic>com/ibm/integrator/XPDintegApplStatusEvent</topic>

          </topics>

          <monitored-bundles>

               <bundle>com.ibm.rcp.integrator.persistencesvc</bundle>

               <bundle>com.ibm.rcp.integrator.rest</bundle>

          </monitored-bundles>

          <monitored-status>

               <status>STOPPED</status>

          </monitored-status>

     </tec-monitor>

     <tec-monitor name="tec2" maintenance-mode="OFF">

…

If concreteStart events should not be sent to TEC, use an empty topics element in the XPDinteg.xml file:

If bundle events should not be sent to TEC, use an empty monitored-bundles element as well as an empty monitored-status element in the XPDinteg.xml file:

<monitored-bundles></monitored-bundles>
<monitored-status></monitored-status>

If the Tivoli Monitoring Service sends CBE events directly to the Tivoli Enterprise Console (TEC) using a direct connection (transport type = SOCKET), only the TEC server name and port number must be specified (see Table 32 and Listing 32).

Listing 32: Configuration of direct TEC (socket) connection in XPDinteg.xml

<monitoring>

…

     <tec-monitor name="tec1">

     <!-- <transport-type>=SOCKET - connect to TEC directly, DISABLE - don't use the iTMS, LCF - use local Tivoli Endpoint -->

          <transport-type>SOCKET</transport-type>

          <hostname>tecserver.heidelberg.de.ibm.com</hostname>

          <port>5529</port>

…

Alternatively, if a locally installed Tivoli Endpoint is used for sending events to the TEC, additional configuration steps are required (see chapter ‎4.10.2 Using Tivoli endpoints on the Sotre Server for forwarding TEC Events). Also, please, make sure that the following DLLs are available:

libteceif.dll
libtecgw.dll
teclcf.dll

These DLLs can be downloaded from the IBM Support Site with the Tivoli Endpoint Fixpack and can be simply copied to the remote server where the Expeditor integrator is located. The DLLs are provided with the Expeditor integrator runtime (<XPDINTEG_HOME>/tools/tec). The Windows PATH variable should point to these DLLs (Alternatively, they can be copied under the system root directory, e.g. C:\WINDOWS). Check the Tivoli support site for latest updates . Refer to APPENDIX B – Technical Details for more details.

Using Tivoli Endpoints on the Store Server for forwarding TEC Events

Setting up the environment

First, the Windows Environment variables from the Tivoli lcf_env.cmd file must be set for sending EIF Events to the TEC Console via the Tivoli Endpoint. Also, the ‘Path’ variable in Windows needs to be appended with the path containing the TEC DLLs. In cases where manual setting is difficult, the provided TeclLcfUitl tool helps to automatically set the Environment variables in rcpinstall.properties as required (see <XPDINTEG_HOME>/tools).
The rcpinstall.properties file is located under: <XPDINTEG_HOME>/rcp/eclipse/plugins/com.ibm.rcp.base_<version>/

It can be used to set the Tivoli Environment variables. The format to be specified is env.set.XXX=YYY. This would set Environment variable XXX to value YYY. If the variable already exists, it will be replaced.

Follow these steps to use this TecLcfUtil to update the rcpinstall.properties file:

Make sure that the Tivoli Endpoint is installed and connectivity to the TEC is available.
Unzip the XPDintegTools.zip file under <XPDINTEG_HOME>/tools to <XPDINTEG_HOME>/tools/XPDintegTools
Edit the teclcf.properties file (Forward slashes ‘/’ must be used in path variables! See example file in chapter ‎4.10.2.3. Sample Files for TECLCF utility):
1. Add the full path to the Tivoli Endpoint's lcf_env.cmd file (use '/' for separator) after the TIVOLI_LCF_CMD_PATH, e.g.
  TIVOLI_LCF_CMD_PATH=C:/WINNT/Tivoli/lcf/1/lcf_env.cmd
2. Edit the XPDINTEG_RCPINSTALL_PROPERTIES_PATH variable and adjust it to the current version of com.ibm.rcp.base_<version>.<build>, e.g.
  XPDINTEG_RCPINSTALL_PROPERTIES_PATH=../../rcp/eclipse/plugins/com.ibm.rcp.base_6.2.1.20100125-2258/rcpinstall.properties
Open a console window and change to the directory of the TecLcfUtil utility (<XPDINTEG_HOME>/tools/XPDintegTools).
Update the rcpinstall.properties under <XPDINTEG_HOME>/rcp/eclipse/plugins/com.ibm.rcp.base_<version>.<build>/ by running the TecLcfUtil.bat.
Note: Please, make sure that the TecLcfUtil.bat points to an existing JRE (by default it points to the JRE provided with the Expeditor integrator).
Open the rcpinstall.properties and note that the file has been updated (See example file in chapter ‎4.10.2.3. Sample Files for TECLCF utility).
Make sure that the following DLLs are available in the operating system path (by either copying them from <XPDINTEG_HOME>/tools/tec into the system path, e.g. C:\WINNT\system32, or by adding the path to these DLLs to the system PATH variable)
- Libteceif.dll,
- libtecgw.dll
- teclcf.dll
It is recommended to reboot Expeditor integrator server now.
Reset Expeditor integrator runtime so that the rcpinstall.properties is re-applied (<XPDINTEG_HOME/resetscript/XPDintegReset.bat>.
Finally, the configuration of Expeditor integrator must be adjusted in the XPDinteg.xml according to Table 32 (see next chapter).

Configuring Expeditor integrator to use the local Tivoli Endpoint

The transport type must be set to LCF to enable forwarding of CBE events to the TEC server through the local Tivoli Endpoint. This can be done directly in the XPDinteg.xml configuration file (see Listing 33) or through the Expeditor integrator configuration UI (under Tivoli Monitoring Service).

Listing 33: Configuration in XPDinteg.xml for using the local Tivoli Endpoint (LCF) to connect to the TEC

<monitoring>

…

     <tec-monitor name="tec1">

     <!-- <transport-type>=SOCKET - connect to TEC directly, DISABLE - don't use the iTMS, LCF - use local Tivoli Endpoint -->

          <transport-type>LCF</transport-type>

…

Note: All events are cached under <XPDINTEG_HOME>/persistent/tec/tivoli.send.cache. This file is used for collecting all Expeditor integrator events which are forwarded to the TEC.

Sample Files for TECLCF utility

This chapter lists examples of files which are configured during the local endpoint configuration.

lcv_env.CMD
Listing 34 shows an example of the lcf_env.cmd file that contains the required settings for using EIF with the local Tivoli Endpoint.

Listing 34: Example for lcf_env.cmd file

@echo off

REM Licensed Materials - Property of IBM

REM

REM 5698-FRA

REM

REM (C) Copyright IBM Corp. 1994, 2005 All Rights Reserved

REM

REM US Government Users Restricted Rights - Use, duplication or

REM disclosure restricted by GSA ADP Schedule Contract with

REM IBM Corp

rem Generated at lcf install time

if not "%LCF_BINDIR%" == "" goto END_ENV

set INTERP=w32-ix86

set LCFROOT=C:\Program Files\Tivoli\lcf

set LCF_INSTANCE=1

set LCF_DATDIR=C:\Program Files\Tivoli\lcf\dat\1

set LCF_BINDIR=%LCFROOT%\bin\%INTERP%\mrt

set LCF_LIBDIR=%LCF_BINDIR%

set LCF_CATDIR=%LCFROOT%\generic\msg_cat

set LCF_TOOLSDIR=%LCFROOT%\bin\%INTERP%\tools

set Path=%LCF_BINDIR%;%Path%

set NLSPATH=%LCF_CATDIR%\%%L\%%N.cat;%LCF_CATDIR%\%%l\%%N.cat;%LCF_CATDIR%\C\%%N.cat;%NLSPATH%

set TISDIR=%LCF_DATDIR%

set BEGINLIBPATH=%LCF_BINDIR%

echo Tivoli LCF environment variables configured.

:END_ENV

echo on

rcpinstall.properties
The rcpinstall.properties file contains all commands required to set the Eclipse start-up environment of the Expeditor integrator. The customized Tivoli environment settings provided in the teclcf.properties file (see Listing 36) will be added to it. Listing 35 shows the original rcpinstall.properties file.

Listing 35: rcpinstall.properties file example

###############################################################################

# Licensed Materials - Property of IBM

# 5724-R09

# (C) Copyright IBM Corp. 2006, 2008 All Rights Reserved.

###############################################################################

Xbootclasspath.append=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.base_6.2.0.200809290300/rcpbootcp.jar

-Dcom.ibm.pvc.webcontainer.port=0

-Declipse.registry.nulltoken=true

-Djava.protocol.handler.pkgs=com.ibm.net.ssl.www.protocol

-Djava.util.logging.config.class=com.ibm.rcp.core.internal.logger.boot.LoggerConfig

library.path.append.win32=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.os.win32_6.2.0.200809290300/os/win32/x86

library.path.append.linux=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.os.linux_6.2.0.200809290300/os/linux/x86

# Override eclipse default for BIDI dir

-Dosgi.nl.user=true

# Eclipse plugin_customization.ini override

plugincustomization=${rcp.home}/rcp/plugin_customization.ini

# Exclude Eclipse logging hook

-Dosgi.hook.configurators.exclude=org.eclipse.core.runtime.internal.adaptor.EclipseLogHook

# Java security file location

-Djava.security.properties=file:${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.base_6.2.0.200809290300/rcp.security.properties

# Java Core dump location. Note this is temp fix for only VM environmental variables

# This ability is not supported in the general case in 6.1

env.set.IBM_JAVACOREDIR=${rcp.data}/logs

env.set.IBM_COREDIR=${rcp.data}/logs

env.set.IBM_HEAPDUMPDIR=${rcp.data}/logs

# JSR47 Logging Configuration

handlers=java.util.logging.ConsoleHandler com.ibm.rcp.core.internal.logger.boot.RCPLogHandler com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.encoding=UTF-8

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.encoding=UTF-8

.level=WARNING

SystemOut.level=INFO

SystemErr.level=INFO

com.ibm.esupport.client.product.SSC4TNF.utils.level=INFO

com.ibm.rcp.core.internal.logger.frameworkhook.level=CONFIG

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.level=WARNING

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.level=FINEST

com.ibm.rcp.lapinvoker.level=INFO

java.util.logging.ConsoleHandler.level=FINEST

java.util.logging.ConsoleHandler.formatter=com.ibm.rcp.core.internal.logger.boot.RCPFormatter

# RCP Logging Configuration

#com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.formatter=com.ibm.rcp.core.internal.logger.boot.RCPFormatter

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.formatter=com.ibm.rcp.core.internal.logger.cbe.CBE101Formatter

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.size=4000000

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.count=6

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.append=false

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.pattern=error-log-%g

# RCP Trace Configuration

#com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.formatter=com.ibm.rcp.core.internal.logger.boot.RCPFormatter

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.formatter=com.ibm.rcp.core.internal.logger.cbe.CBE101Formatter

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.size=4000000

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.count=6

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.append=false

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.pattern=trace-log-%g

resetDir.com.ibm.rcp.portal.app=com.ibm.rcp.portal.app

resetDir.com.ibm.portal.cai=com.ibm.portal.cai

resetDir.com.ibm.rcp.topologyhandler=com.ibm.rcp.topologyhandler

resetDir.com.ibm.rcp.managedsettings=com.ibm.rcp.managedsettings

# Framework extensions for logging

# For 6.1.2 all -Dosgi.framework.extensions must be specified in jvm.properties

# MacOS X Requires the framework extension value for 6.1.2 so add it in a platform specific style

# rcplauncher binary filters this property such that only Mac platforms will use it

vmarg.osgi.framework.extensions.macosx=-Dosgi.framework.extensions=com.ibm.rcp.core.logger.frameworkhook

teclcf.properties
This file contains the customized lines for the environment settings which are required for the Expeditor integrator Tivoli Monitor Service (iTMS) to use the local Tivoli Endpoint for forwarding the application events to the TEC. Listing 36 shows the lines that contain the settings of the local installation environment (Store Server) where the Expeditor integrator is installed.

Listing 36: Customized teclcf.properties example

#This File updated on Wed Jan 23 16:41:27 IST 2008

#Wed Jan 23 16:41:27 IST 2008

#Specify the full path to the Tivoli Endpoint's lcf_env.cmd file - use '/' for separator

#Example: TIVOLI_LCF_CMD_PATH=C:/WINNT/Tivoli/lcf/1/lcf_env.cmd

TIVOLI_LCF_CMD_PATH=C:/WINNT/Tivoli/lcf/1/lcf_env.cmd

#Specify the relative path to the rcpinstall.properties - use '/' for separator

#Example: XPDINTEG_RCPINSTALL_PROPERTIES_PATH=../../rcp/eclipse/plugins/com.ibm.rcp.base_<version>.<build>/rcpinstall.properties

XPDINTEG_RCPINSTALL_PROPERTIES_PATH=../../rcp/eclipse/plugins/com.ibm.rcp.base_6.2.1.20100125-2258/rcpinstall.properties

#Specify the relative path to the path where TEC DLLs are present - use '/' for separator

#Example: TEC_DLL_PATH=../tec

TEC_DLL_PATH=../tec

rcpinstall.properties(OUTPUT)
After running the TecLcfUtil.bat the rcpinstall.properties file will contain the customized Tivoli Endpoint environment settings (see Listing 37).

Listing 37: Customized rcpinstall.properties file (including Tivoli Endpoint environment settings)

###############################################################################

# Licensed Materials - Property of IBM

# 5724-R09

# (C) Copyright IBM Corp. 2006, 2008 All Rights Reserved.

###############################################################################

Xbootclasspath.append=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.base_6.2.0.200809290300/rcpbootcp.jar

-Dcom.ibm.pvc.webcontainer.port=0

-Declipse.registry.nulltoken=true

-Djava.protocol.handler.pkgs=com.ibm.net.ssl.www.protocol

-Djava.util.logging.config.class=com.ibm.rcp.core.internal.logger.boot.LoggerConfig

library.path.append.win32=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.os.win32_6.2.0.200809290300/os/win32/x86;C\:/Program Files/Tivoli/lcf/bin/w32-ix86/mrt;C\:/Program Files/IBM/Lotus/Expeditor/tools/tec

library.path.append.linux=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.os.linux_6.2.0.200809290300/os/linux/x86

# Override eclipse default for BIDI dir

-Dosgi.nl.user=true

# Eclipse plugin_customization.ini override

plugincustomization=${rcp.home}/rcp/plugin_customization.ini

# Exclude Eclipse logging hook

-Dosgi.hook.configurators.exclude=org.eclipse.core.runtime.internal.adaptor.EclipseLogHook

# Java security file location

-Djava.security.properties=file:${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.base_6.2.0.200809290300/rcp.security.properties

# Java Core dump location. Note this is temp fix for only VM environmental variables

# This ability is not supported in the general case in 6.1

env.set.IBM_JAVACOREDIR=${rcp.data}/logs

env.set.IBM_COREDIR=${rcp.data}/logs

env.set.IBM_HEAPDUMPDIR=${rcp.data}/logs

# JSR47 Logging Configuration

handlers=java.util.logging.ConsoleHandler com.ibm.rcp.core.internal.logger.boot.RCPLogHandler com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.encoding=UTF-8

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.encoding=UTF-8

.level=WARNING

SystemOut.level=INFO

SystemErr.level=INFO

com.ibm.esupport.client.product.SSC4TNF.utils.level=INFO

com.ibm.rcp.core.internal.logger.frameworkhook.level=CONFIG

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.level=WARNING

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.level=FINEST

com.ibm.rcp.lapinvoker.level=INFO

java.util.logging.ConsoleHandler.level=FINEST

java.util.logging.ConsoleHandler.formatter=com.ibm.rcp.core.internal.logger.boot.RCPFormatter

# RCP Logging Configuration

#com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.formatter=com.ibm.rcp.core.internal.logger.boot.RCPFormatter

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.formatter=com.ibm.rcp.core.internal.logger.cbe.CBE101Formatter

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.size=4000000

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.count=6

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.append=false

com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.pattern=error-log-%g

# RCP Trace Configuration

#com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.formatter=com.ibm.rcp.core.internal.logger.boot.RCPFormatter

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.formatter=com.ibm.rcp.core.internal.logger.cbe.CBE101Formatter

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.size=4000000

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.count=6

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.append=false

com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.pattern=trace-log-%g

resetDir.com.ibm.rcp.portal.app=com.ibm.rcp.portal.app

resetDir.com.ibm.portal.cai=com.ibm.portal.cai

resetDir.com.ibm.rcp.topologyhandler=com.ibm.rcp.topologyhandler

resetDir.com.ibm.rcp.managedsettings=com.ibm.rcp.managedsettings

# Framework extensions for logging

# For 6.1.2 all -Dosgi.framework.extensions must be specified in jvm.properties

# MacOS X Requires the framework extension value for 6.1.2 so add it in a platform specific style

# rcplauncher binary filters this property such that only Mac platforms will use it

vmarg.osgi.framework.extensions.macosx=-Dosgi.framework.extensions=com.ibm.rcp.core.logger.frameworkhook

# Tivoli LCF Windows Environment Variables Configuration

env.set.INTERP=w32-ix86

env.set.LCFROOT=C\:/Program Files/Tivoli/lcf

env.set.LCF_INSTANCE=1

env.set.LCF_DATDIR=C\:/Program Files/Tivoli/lcf/dat/1

env.set.LCF_BINDIR=C\:/Program Files/Tivoli/lcf/bin/w32-ix86/mrt

env.set.LCF_LIBDIR=C\:/Program Files/Tivoli/lcf/bin/w32-ix86/mrt

env.set.LCF_CATDIR=C\:/Program Files/Tivoli/lcf/generic/msg_cat

env.set.LCF_TOOLSDIR=C\:/Program Files/Tivoli/lcf/bin/w32-ix86/tools

env.set.NLSPATH=C\:/Program Files/Tivoli/lcf/generic/msg_cat/%%L/%%N.cat;C\:/Program Files/Tivoli/lcf/generic/msg_cat/%%l/%%N.cat;C\:/Program Files/Tivoli/lcf/generic/msg_cat/C/%%N.cat

env.set.TISDIR=C\:/Program Files/Tivoli/lcf/dat/1

env.set.BEGINLIBPATH=C\:/Program Files/Tivoli/lcf/bin/w32-ix86/mrt

LINES APPENDED TO RCPINSTALL.PROPERTIES (INPUT)
The following lines in Listing 38 are appended to the input rcpinstall.properties from Listing 35.

Listing 38: Tivoli Endpoint environment settings that are added to the rcpinstall.properties file

# Tivoli LCF Windows Environment Variables Configuration

env.set.INTERP=w32-ix86

env.set.LCFROOT=C\:/Program Files/Tivoli/lcf

env.set.LCF_INSTANCE=1

env.set.LCF_DATDIR=C\:/Program Files/Tivoli/lcf/dat/1

env.set.LCF_BINDIR=C\:/Program Files/Tivoli/lcf/bin/w32-ix86/mrt

env.set.LCF_LIBDIR=C\:/Program Files/Tivoli/lcf/bin/w32-ix86/mrt

env.set.LCF_CATDIR=C\:/Program Files/Tivoli/lcf/generic/msg_cat

env.set.LCF_TOOLSDIR=C\:/Program Files/Tivoli/lcf/bin/w32-ix86/tools

env.set.NLSPATH=C\:/Program Files/Tivoli/lcf/generic/msg_cat/%%L/%%N.cat;C\:/Program Files/Tivoli/lcf/generic/msg_cat/%%l/%%N.cat;C\:/Program Files/Tivoli/lcf/generic/msg_cat/C/%%N.cat

env.set.TISDIR=C\:/Program Files/Tivoli/lcf/dat/1

env.set.BEGINLIBPATH=C\:/Program Files/Tivoli/lcf/bin/w32-ix86/mrt

Also, the line:

library.path.append.win32=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.os.win32_6.2.0.200809290300/os/win32/x86

is changed to

library.path.append.win32=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.os.win32_6.2.0.200809290300/os/win32/x86;C\:/Program Files/Tivoli/lcf/bin/w32-ix86/mrt;C\:/Program Files/IBM/Lotus/Expeditor/tools/tec

Note:

Run the TecLcfUtil.bat only once, else the rcpinstall.properties will have duplicate entries for the Environment variables, which will result in an inconsistent state for rcpinstall.properties. If the rcpinstall.properties goes to an inconsistent state at any point, delete it and rename the rcpinstall.properties.bak (backed up by our utility) located in the same directory to rcpinstall.properties and re-run TecLcfUtil.bat
The format <XPDINTEG_HOME>/tools/tec (the backslash before the colon) is needed for absolute paths in rcpinstall.properties
It is not recommended to change the values for properties TEC_DLL_PATH and XPDINTEG_RCPINSTALL_PROPERTIES_PATH in teclcf.properties (see Listing 35). They are only included to provide flexibility if we ever wish to change the TEC DLLs path and update the version of the com.ibm.rcp.base plugin for future versions of the Expeditor integrator
Also, make sure that the absolute path for the TEC DLLs on the file-system (including the DLL name and extension ‘dll’) do not have more than 68 characters. Else, DLLs fail to load in Windows 2000. So, it is recommended that the Expeditor integrator is installed at e.g. C:/XPDINTEG, then the dlls would be in C:/XPDINTEG/tools/tec

Further Services

House Keeping for Expeditor integrator Runtime (Section_10)

Expeditor integrator was especially designed for stable, reliable, headless and remote operation.
The House Keeping feature has been developed to avoid the Expeditor integrator runtime and the remote server on which Expeditor integrator is installed on facing problems due to

unprocessed messages
indefinetely growing queues and files
blocked and looping ACS flows
or other lack of resources.

The House Keeping is implemented as ACS Flow (Default_HouseKeeping.flow) which can be configured to run periodically (e.g. once a week). This flow is triggered by an event which fired by the SampleHouseKeepingAdapter (see Generic Resource Adapter example in Listing 21).
If House Keeping is not required, the Default_HouseKeeping.flow file can be removed from the <XPDINTEG_HOME>/flowdefs/system directory.
More configuration details are provided in chapter ‎6.7 House Keeping Flow.

Transaction Service Configuration (Section_15)

The Transaction Service provides transactional reliability to Expeditor integrator Application Control Service Flows (ACS Flows).
General format:

<transaction-service>

     <log-size>log_file_size_in_kbyte</log-size>

     <persistence-directory>my_persistence_log&trace_directory</persistence-directory>

     <trace-setting>ON_or_ALL</trace-setting>

</transaction-service>

The following table contains possible configuration parameters.

Table 34: Transaction Service configuration parameters

Property	Explanation
<transaction-service>	Tag indicating Transaction Service configuration section
<log-size>	Integer: size of the created transaction log file in kByte
<persistence-directory>	directory for the transaction log and trace files; default <XPDINTEG_HOME>/persistence/txlogdir
<trace-setting>	ON or ALL Switches tracing of all transactions off or on. Please, be aware of performance impacts when tracing is switched on!

The default configuration setting is given in Table 35.

Table 35: Sample configuration for the Transaction Service (max. log file size = 102 MB and tracing is switched off)

<transaction-service>

<log-size>102400</log-size>
<persistence-directory>persistent/txlogdir</persistence-directory>
<trace-setting>OFF</trace-setting>

</transaction-service>

Persistence Service Configuration (Section_16)

The Persistence Service is used to for storing important information to the local Expeditor client database. It allows persisiting Business Events, Log Events, Application Status Events and Bundle Events. For example, temporary stored information can be used for keeping track of application status information. This information could be retrieved by other service, e.g. by a monitoring service or the REST Adapter for its HTTP Response message.
Note: Be careful with using the Persistence Service, because the used database operation has strong performance impact!

The Persistence Service can be configured as follows.

General Format:

<persistence-service>

     <database-configuration>

          <param name="DBURI" value="jdbc:derby:persistent/PersistentStore;create=true"/>

          <param name="DRIVER_CLASS" value="org.apache.derby.jdbc.EmbeddedDriver"/>

          <param name="USER" value="xpdinteg"/>

          <param name="PASSWORD" value="xpdinteg"/>

     </database-configuration>

     <persist>

          <business-event persistence="ON">

               <filter-topics>

                    <topic>com/ibm/integrator/businessevent/*</topic>

...

          <appl-status-event persistence="ON">

               <filter-topics>

                    <topic>com/ibm/integrator/XPDintegApplStatusEvent</topic>

...

          <log-event persistence="ON">

               <threshold>WARNING</threshold>

               <monitored-bundles>

                    <bundle>com.ibm.rcp.integrator.acsvc</bundle>

...

          <bundle-event persistence="ON">

               <monitored-bundles>

                    <bundle>com.ibm.rcp.integrator.queuedispatchersvc</bundle>

               </monitored-bundles>

               <monitored-status>

                    <status>STARTED</status>

                    <status>STOPPED</status>

               </monitored-status>

Table 36 describes in detail the different configuration parameters.

Table 36: Persistence Service configuration properties

Property	Explanation
<persistence-service>	Tag indicating Transaction Service configuration section in the XPDinteg.xml file
<database-configuration>	Tag under which the local (Derby) database access parameters are configured.
<param name="DBURI" value=	"jdbc:derby:persistent/PersistentStore;create=true“ Provides the database URI access parameters.
<param name="DRIVER_CLASS" value=	Fully qualified Driver Class Name for the local (Derby) database access. Default: value=”org.apache.derby.jdbc.EmbeddedDriver"/>
<param name="USER" value=	UserName to connect to the DB (optional), default: value="xpdinteg"
<param name="PASSWORD" value=	Password to connect to the DB (optional), default: value="xpdinteg
<*business-event* persistence=	Tag for activating persistence of Business Events possible values: "ON" or "OFF"
<persist> <business-event> <filter-topics>	Contains a list of Business Event topics (separated by the <topic> tag) which the Persistence Service is subscribed to. The Persistence Service will save these events to the configured local database.
<topic>	A single <topic> tag contains one topic. Wildcards are allowed for the business event topics.
<*appl-status-event* persistence=	Flag for activating persistence application Status Events. Possible values: "ON" or "OFF"
<appl-status-event> <filter-topics>	Contains a list of Application Status Event topics (separated by the <topic> tag) which the Persistence Service is subscribed to. The Persistence Service will save these events to the configured local database.
<topic>	A single <topic> tag contains one topic to be considered for persistence. Multiple topics require multiple <topic> tags.
<*log-event* persistence=	Flag for activating persistence of Log Events possible values: "ON" or "OFF"
<threshold>	Log threshold for filtering and persisting the Log Events possible values: {DEBUG \| INFO \| WARNING \| ERROR}
<monitored-bundles>	Contains a list of bundles from which Log Events are persisted. If no value is specified, log events from all the bundles are filtered and persisted.
<bundle>	A single <bundle> tag contains on bundle for which Log Events are persisted.
<*bundle-event* persistence=	Flag for activating persistence of Bundle Events possible values: {ON \| OFF}
<monitored-bundles>	Contains a list of bundles from which the Bundle Events are persisted. If no value is specified, bundle events from all the bundles are filtered and persisted
<bundle>	A single <bundle> tag contains one bundle for which Bundle Events are persisted.
<monitored-status>	Contains a list of states for which the Bundle Events are persisted. If no value is specified, all the bundle state changes are filtered and persisted.
<status>	A single <status> tag contains one monitored status. Possible values are: {INSTALLED \| STARTED \| STOPPED}

Listing 39 provides an example for Pesistence Service configuration.

Listing 39: Persistence Service example configuration

<persistence-service>

     <database-configuration>

          <param name="DBURI" value="jdbc:derby:persistent/PersistentStore;create=true"/>

          <param name="DRIVER_CLASS" value="org.apache.derby.jdbc.EmbeddedDriver"/>

          <!--<param name="DATA_SOURCE_KEY" value="XXXXXXX"/>-->

          <param name="USER" value="xpdinteg"/>

          <param name="PASSWORD" value="xpdinteg"/>

     </database-configuration>

     <persist>

          <business-event persistence="ON">

               <filter-topics>

                    <topic>com/ibm/integrator/businessevent/*</topic>

               </filter-topics>

          </business-event>

          <appl-status-event persistence="ON">

               <filter-topics>

                    <topic>com/ibm/integrator/XPDintegApplStatusEvent</topic>

               </filter-topics>

          </appl-status-event>

          <log-event persistence="ON">

               <threshold>WARNING</threshold>

               <monitored-bundles>

                    <bundle>com.ibm.rcp.integrator.acsvc</bundle>

               </monitored-bundles>

          </log-event>

          <bundle-event persistence="ON">

               <monitored-bundles>

                    <bundle>com.ibm.rcp.integrator.queuedispatchersvc</bundle>

               </monitored-bundles>

               <monitored-status>

                    <status>STARTED</status>

                    <status>STOPPED</status>

               </monitored-status>

          </bundle-event>

     </persist>

</persistence-service>

Password encryption utility

The XPDinteg.xml file contains resource access credentials (e.g. for FTP Servers). These credentials can be provided in the clear or encrypted (indicated by {xor}). For the latter case, a small password encryption tool is provided with the Expeditor integrator (see /tools/PasswordUtil sub folder). This password utility is a command line tool that reads the password provided in the passwordutil.properties file and encrypts it appropriately.

Follow these steps to encrypt a password:

Unzip the PasswordUtil.zip file under the <XPDINTEG_HOME>/tools/PasswordUtil.zip
Edit the password.properties file and add your password after the password parameter. Save and close the file
1. e.g. password=mgirealibm
Open a console window and change to the directory of the password utility (<XPDINTEG_HOME>/tools/PasswordUtil).
Encrypt your provided password by running the PasswordUtil.bat .
Open the password.properties file again and copy the now encrypted password into your target file (e.g. the XPDinteg.xml file). The keyword {xor} indicates that the following characters are encrypted.

Note: Please, make sure that the PasswordUtil.bat points to an existing JDK (by default it points to the JDK provided with the Expeditor integrator; compare resetscript/XPDintegReset.bat in chapter ‎5.1 Start/Stop Expeditor integrator)